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most powerful development tool 
the recycling genius of edwin hoogerbeets? 


If Edwin Hoogerbeets were a developer, 
he'd be a proud man. Because the new 
Microsoft® Visual C++" 4.0 is based on 
the very principle he lives by: 


Never create from scratch. 


Who is Edwin Hoogerbeets? A 
recycling genius who sees every 
used object as an opportunity 
for creative brilliance. The same 
way a developer might if he or 
she used new Visual C++ 4.0. 
No other development tool offers 
such reusability, allowing you to 
deliver more robust applications 
in less time. 


Now you can recycle just about 
anything —but you don’t have 
to be a genius to do it. The new 
Component Gallery allows you to 
store and reuse your own C++ 
components and OLE controls, 
as well as 3rd-party components. 
To get you started, we've already 
included prebuilt components 
that deliver key application 
functionality. And, MFC 4.0 gives 
you more than 150 classes and 
120,000 lines of code you don’t 
have to write or test. 


Egghead . 
(800) 741-4395 


Softmart 
(800) 328-1319 


The new Developer Studio 
makes reusability intuitive. With 
ClassView, you can view relation- 
ships between classes, rather 
than a screen full of files. You'll 
even have one-click access to 
the MSDN Development Library, 
Microsoft Visual Test, Fortran 
PowerStation, and Microsoft 
Visual SourceSafe™ version 
control system. And of course, 
expanded C++ language support, 
including namespaces and RTT, 
gives you added flexibility. 


Now that you have a better 

idea of what’s possible 

when you recycle, start with 

a Visual C++ Subscription, 
which includes the Visual C++ 
development system 4.0, plus 
three additional Subscription 
Releases shipped automatically. 


For more information about the 
Visual C++ 4.0 Subscription, 

or to get your free Developer 
Roadmap evaluation CD, call 
(800) 719-5577, Dept. 4KD. 
You can also get information at 
http: //www.microsoft.com/visualc 
or by calling one of the resellers 
listed below. Who knows? You 
just might become the next 
Edwin Hoogerbeets. 


Stream 


(800) 835-0625 





om 


Subscription 


= iC soft ‘ 
r, A hcoualC+ 
ma] 


Component Gallery. 
Quick access to OLE 
controls and reusable 


C++ components. 


MFC 4.0 Library. 
Adds latest support for 


Windows® 95 controls. 


Client-Server Support. 
Built-in Jet database engine 
and ODBC support to 


access enterprise data. 


Custom AppWizard. 
Create your own 
AppWiczard for 
your unique 


application needs. 


Multiple Platform Support. 
Target Intel®, RISC*, and 
Macintosh™ platforms 


with a single codebase. 


CDW 
(800) 858-4CDW (4239) 


* Versions of Visual C++ 4.0 for RISC and Macintosh available separately. © 1995 Microsoft Corporation. All rights reserved. Microsoft and 
Windows are registered trademarks and Visual C++, Visual SourceSafe, and Where do you want to go today? are trademarks of Microsoft 
Corporation. Intel is a registered trademark of Intel Corporation. Macintosh is a registered trademark of Apple Computer, Inc. 
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PROPOSING A STANDARD WEB API 18 
by Michael Doyle, Cheong Ang, and David Martin 

At last count, there were nearly a dozen APIs vying for hearts and home pages of Web 

developers. Our authors propose a standard API that leverages the concept of 

embedded executable content for interactive application development and delivery. 


IMPROVING KERMIT PERFORMANCE 28 
by Tim Kientzle 

Tim compares the error-handling strategies of a variety of popular protocols, then 

presents heuristics that improve the performance of Kermit’s windowing strategy. 


CGI AND THE WORLD WIDE WEB 42 
by G. Dinesh Dutt 

The Common Gateway Interface (CGI) makes it possible for Web servers to interact with 

external programs. Dinesh presents a program that reports gateway-execution errors. 


USING SERVER-SIDE INCLUDES 52 
by Matt Kruse 

Server-side includes are commands embedded inside HTML documents that enable your 

page to do something different each time it is loaded. Matt describes the format of these 
commands and shows how to write programs that work with your Web pages. 


JAVA COMMAND-LINE ARGUMENTS 58 
by Greg White 

Greg introduces a package of Java classes that parse the command-line parameters for 

HtmlXlate, an application that converts HTML to RTF. Because HtmlXlate doesn’t require 

display graphics, Greg made it an “application” instead of an “applet.” 


IMPLEMENTING MULTILEVEL UNDO/REDO 64 
by Jim Beveridge 

The Undo/Redo mechanism Jim presents here is based on a history length limited only 

by available memory. Because it is implemented in Visual C++ and MFC, this 

mechanism can easily be added to your applications. 
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EMBEDDED SYSTEMS 


NETWORKING INTELLIGENT DEVICES 68 
by Gil Gameiro 

Novell’s Embedded Systems Technology (NEST) lets you incorporate network protocols 

and client services into embedded systems. Gil uses NEST to put an intelligent coffee 

maker online, then controls it with a Windows-hosted menu program. 


NETWORKED SYSTEMS 


FAST NETWORKING WITH WINSOCK 2.0 16 
by Derek Brown and Martin Hall 

, Derek and Martin show how you can get maximum performance from WinSock 2.0 
ee : applications by taking advantage of two features new to the spec—event objects and 

overlapped I/O. 
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EXAMINING ROOM 


EXAMINING ROGUEWAVE’S TOOLS.H++ 

by P.W. Scherer 

RogueWave’s Tools.h++, a C++ library consisting of more than 100 classes, has been the 
cornerstone of Perry's development efforts ever since he ported over 30,000 lines of C++ 
code to an equivalent app that was only 6000 lines long. 


PROGRAMMER'’S WORKBENCH 


LEX AND YACC 


by lan E. Gorman 
lan describes how he used traditional compiler-development techniques and the MKS 
Lex & Yacc Toolkit to build a keyword-query compiler for a CD-ROM database. 
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80 
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PROGRAMMING PARADIGMS 

by Michael Swaine 

Before continuing his examination of little languages for the Macintosh, Michael looks at 
a number of books devoted to HTML coding. 


C PROGRAMMING 

by Al Stevens 

Al launches “Quincy 96,” a C/C++ interpreter that runs under Windows 95 and is based 
on GNU C and C++. Among other features, Quincy 96 manages two kinds of 
documents—project documents and text source-code documents. 


ALGORITHM ALLEY 

edited by Bruce Schneier 

Binary searches are algorithmic staples that can be used in just about any program. 
Micha Hofri sees how efficient he can make a basic binary-search algorithm. 


PROGRAMMER’S BOOKSHELF 

by Dean Gablon 

Dean compares Practical Algorithms for C Programmers, by Andrew Binstock and John 
Rex, and Practical Algorithms in C++, by Bryan Flamig. 
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SWAINE’S FLAMES 144 
by Michael Swaine 


PROGRAMMER'S 
SERVICES 


OF INTEREST 142 
by Monica E. Berg 


SOURCE CODE 
AVAILABILITY 


As a service to our readers, all source 
code is available on a single disk and 
online. To order the disk, send $14.95 
(California residents add sales tax) to Dr. 
Dobb’s Journal, 411 Borel Ave., San 
Mateo, CA 94402, call 415-655-4100 x5701, 
or use your credit card to order by fax, 
415-358-9749. Specify issue number and 
disk format. Code is also available through 
the DDJ Forum on CompuServe (type GO 
DDJ), via anonymous FTP from site 
ftp.mv.com (192.80.84.3) in the /pub/ddj 
directory, on the World Wide Web at 
http://www.ddj.com, and through DDJ 
Online, a free service accessible via direct 


dial at 415-358-8857 (14.4 bps, 8-N-1). 








NEXT MONTH 


Little languages are a big deal to most 
programmers—and they're the focus of 
our March issue. 














PKZIP version 2.0 


PC WORLD PKWARE introduces the next generation of its 
award winning compression utility. PKZIP 2.0 yields 
greater performance levels than achieved with 
previous releases of the software. PKZIP compresses 
and archives files. This saves disk space and reduces 
file transfer time. 

Software developers! You can significantly reduce 

WORLD CLASS product duplication costs by decreasing the number 

AWARD of disks required to distribute your applications. 
Call for Distribution License information. 


Software developers! Save disk space and 
media costs with smaller executables. You 
can distribute your software ina 
compressed form with PKLITE Professional'Y 
PKLITE Professional™gives you the ability to 
compress files so that they cannot be 
expanded by PKLITE. This discourages 
reverse engineering of your programs. 





PKLITE increases your valuable disk space by compressing DOS 
executable (.EXE and .COM) files by an average of 45%. The 
operation of PKLITE is transparent, all you will notice is more 


Compression for YOUR Application 


The PKWARE Data Compression 
Library products allow you to 
incorporate data compression 
technology into your software 
applications. The application program 
controls all the input and output of 
data, allowing data to be compressed 
or extracted to or from any device or 


area of area of memory. Not compatible 
with files created by PKZIP. 





All Purpose Data Compression Algorithm compresses ASCII or 
binary data quickly. The routines can be used with most popular 
DOS languages. Separate DOS, Windows, OS/2 32-bit, Win32, UNIX, 
and DOS 32-bit versions are available! 





9025 N. Deerwood Drive 


Brown Deer, WI 53223-2437 
Phone:(414)354-8699 Fax:(414)354-8559 
WWW: http://www.pkware.com 


PRZIP 347 PKLITE $46  PRLITE Professional - $146 
PRWARE Data Compression Library: for DOS - $275 for Windows - $350 for OS72 - $340 
for UNIX (specify version of SCO, Linux, AIX, UnixWare, or Sun Solaris) - $450 
for Win32 (specily for Alpha, Intel or PowerPC) - $3850 
Please add 95.00 S&H per package in the US & Canada, $11.25 per package overseas. 
Wisconsin residents add appropriate state sales tax & county sales tax, 

Cheek or Money Order in US Funds, drawn on a US bank in the US, the American Express 

Card, VISA and MasterCard accepted, no COD orders. 
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O0 technology may look compelling. 


But there’s an unmistakable feeling of 
danger in the air. 


What about our current programming skills? 


What about our existing systems? 
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The benefits of OO can be thrilling: 


Can your 
faster development, reduced back- 


software 
o this? 





logs and a real competitive edge. But 
the reality is there are no quick fixes. And you have 
to think about systems and skills you already have. 

With IBM C++ technology, however, you can 
use a consistent set of tools to deploy fast, highly 
reliable applications throughout the enterprise. You 
can start small, on any platform, without facing an 
impossible learning curve. 

To assure both scalability and portability, IBM’s 
powerful C++ tools and Open Class Library are 
available on platforms from IBM and others: They 
work seamlessly with DB2) CICS"and IMS*'as well 


as other host and server software. They also let you 
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To boost development speed, 






our VisualAge” environment allows 
you to construct applications by 
graphically connecting a Series gy | | (H+ 
of on-screen objects. As InfoWorld 
says, it’s “a masterpiece of visual programming. | 
Visit us at http://www.software.ibm.com for 


details or call 1 800 IBM-3333, Dept. JAOI0, for a 
free Enterprise OO Adoption Kit. We can show you 


how to make the move to OO — one step at a time. 





Solutions for a small planet’ 


*IBM C++ is available on 0/2, AIX, Solaris, OS/400 and MVS (and soon on Windows 95 and NT). In Canada, call 1 800 565-SW4U. Outside North America, contact your local IBM office. The IBM home page is located at http://www.ibm.com. IBM, DB2,0S/2, 


AIX and OS/400 are registered trademarks and CICS, IMS, VisualAge and Solutions for a small planet are trademarks of International Business Machines Corporation. Windows is a registered trademark of Microsoft Corp. © 1995 IBM Corp. All rights reserved. 
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Not Without 
Controversy 


EDITORIAL 


literature would be immune to controversy. But then Sven Birkets, noted critic, author of the 
acclaimed book The Gutenberg Elegies: The Fate of Reading in an Electronic Age, and self- 
appointed latter-day Luddite has an excuse— it’s his editor’s fault. Isn’t it always. 

Birkets’s The Gutenberg Elegies is a wonderfully written, thought- provoking examination of the 
impact of digital technology on literature and reading. Presumably, it was the book— in particular 
the final chapter entitled “Coda: The Faustian Pact”— that led to Birkets’s participation in an 
August 1995 Harper's Magazine forum dubbed “What Are We Doing On-line?”. Along with the 
Electronic Frontier Foundation’s John Perry Barlow, Wired magazine’s Kevin Kelly, and like- 
minded author Mark Slouka, Birkets debated in print the pros and cons of the “message of this 
new medium,” the Internet. Birkets was the resident skeptic. 

Still, nothing Birkets said in Harper's matched his “Coda” chapter, which ends with the 
exhortation “Refuse it.” I'll let you guess (or at least read on your own) what he wants us to shy 
away from. Birkets may be on to something when he says, “my core fear is that we 
are...becoming shallower” and “our whole economic and technological obsession with getting on- 
line is leading us away...from the premise that individualism and circuited interconnection are, at 
a primary level, inimical notions.” In any event, it is entirely proper to question basic premises as 
our online experience evolves. 

Letters to the editor in subsequent Harper's were hot and heavy, with Birkets even having Rilke 
poems thrown back at him. It’s doubtful that analyzing imagery in the works of Virginia Woolf 
ever created such a firestorm. 

All of this led me to go hear Birkets when he showed up at a local bookstore. He agreed, for 
instance, that the “Coda” chapter was the most controversial — and newsworthy— part of the 
book. More interestingly, “Coda” wasn’t part of the original manuscript— it was added when his 
editor sensed something was lacking. What the book needed, said the editor, was a more 
powerful ending. Birkets returned to his Smith-Corona (what else?) and wrote “Coda,” launching 
him on to the literati equivalent of day-time talk shows. 

While Birkets’s editor is possibly an exception, sometimes we editors do end up eating crow. 
Not that I’d ever fess up to feasting on such foul fowl, but even editors can change their minds 
once in a while. 

For instance, regular readers of this space (both of you) may recall that in the November 1995 
issue, I made a smart-aleck remark about a University of California software patent covering 
embedded executable content (“applets”) and the World Wide Web. Shortly thereafter, I heard 
from Michael Doyle, chairman of Eolas Technologies and co-inventor of the patented technique. 
Michael set me straight on the licensing terms of patent, pointing out that Eolas, which holds 
exclusive rights to the patent, is not asking programmers to pay royalties for developing software 
that runs applets. Instead, Eolas is only requiring that developers adhere to a standard API for 
Web development. 

Michael gladly put his comments in writing, which we published in the January 1996 “Letters” 
column. For this issue, Michael— along with Eolas cofounders Cheong Ang and David Martin— 
wrote our lead article, which delves into the history and technical underpinnings of their work. 

By using the patent as a carrot instead of a stick, Eolas has taken a step in helping 
programmers get on with the job of developing next-generation, interactive Web applications. 
Clearly, supporting a single standard API is better than tinkering with a dozen or so competing 
ones. (This problem of dealing with competing APIs is partly behind the current campaign to 
eradicate those annoying “enhanced for Netscape” tags.) The bottom line is that both developers 
and users want a standard. 

This isn’t to say that I’ve changed my mind about software patents. I’ve yet to see how they’ve 
helped the software industry move forward. On the surface, however, the Eolas proposal may be 
an exception. Of course, there’s nothing to say that Eolas will be successful. In all likelihood, 
browser vendors will continue to plod along their proprietary paths, much like operating-system 
vendors of a decade ago (remember TRS-DOS?). 

You don’t have to agree or disagree with the concept of software patents to appreciate the 
spirit of Eolas’s proposal. If nothing else, Doyle and crew should be commended for coming up 
with a creative approach to a thorny problem. Doyle’s article— and the proposal it makes— is 
certainly one of the more controversial pieces we've recently published. I look forward to hearing 


from you about both the article and the proposal. 


Jonathan Erickson 
editor-in-chief 


Vie: think that someone who’s devoted his professional life to writing about “serious” 
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Portability everyone 
can agree on 





“Zinc’s portability 1s transparent. 
And only Zinc has a full set of UI 
objects and real extensibility to develop 
commercial-grade applications. Full 
source code 1s a big plus, too.” 


DEVELOPMENT MANAGER 





“We're now shipping our 
application on every major platform 
and in every major world market. 


Our sales force loves it! With Zinc 
we're beating the competition. : 


MARKETING MANAGER 





“Zinc cost us very little up front and 
saved us years of development expense. 
Revenue 1s up, thanks to the new mar- 

kets [Zinc enabled us to enter]. 
I'm very satisfied.” 


FINANCE MANAGER 


When was the last time Development, Marketing, and 
Finance all agreed on anything? Now’s your chance to 
make it happen. With Zinc you'll build better applica- 
tions, on more platforms, in less time, and with less 


money—and that's a promise. 


Only Zinc offers complete portability. 

Since Zinc Application Framework is the only cross- 
platform tool that delivers |00% portability, you'll have 
your applications on other platforms as fast as you can 
recompile. And no one supports as many platforms as 
Zinc does. It’s all part of what makes Zinc the most 
productive—and affordable—tool you can own. 


Productivity that leads to opportunity. 

Zinc zips through tedious tasks with C++ object ori- 
entation and a unique visual development tool. And, 
enabling your application for international markets Is 
already done—just translate your text. Plus, Zinc is the 


only tool that supplies 100% of the source code. 

It all adds up to productivity. Which means more 
profitability. Which means everybody's happy— 
especially you. 


LABS “This product is 
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JAN. 30, 1995 personally seen for the 
international engineer. " 





“Developers seeking easy 
delivery of GUI applications... 
will find Zinc their best 
option by far." 


Multilingual 
Computing 





“Best Portability” 


“Zinc came closest of all the products we tested to 


INFOWORLD our ideal of portability... In short, Zinc did a great 


February 6, 1995 job." 


For free demonstration software and an infor- 


mation packet, call toll-free: 


1-800-638-8665 


USA: +1 801 785 8900 or fax +1 801 785 8996 
Europe: +44 (0) 181 855 9918 or fax +44 (0) 181 316 2211 
Asia: +81 (052) 733 4301 or fax +81 (052) 733 4328 
Electronically: Info@zinc.com or GO ZINC on CompuServe. 


Web: http://www.zinc.com/ Ftp: ftp://ftp.zinc.com/ 
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Ada 95 Classes 

Dear DDI, 

I read with interest the article “Object- 
Oriented Facilities in Ada 95,” by David 
L. Moore (DDJ, October 1995). It is good 
to see the discussion of a fine program- 
ming language. 

However, Moore’s statement that 
“Line'Class and Object'Class represent the 
same type; there is one class-wide type 
for any tree of derivations, rather than 
one for every subtree” is contrary to fact. 
There is indeed a class-wide type for ev- 
ery subtree. If Object and Line are de- 
fined as in Example 1, then you can ac- 
cess the Offset field of a value of type 
Line'Class. Doing so with a value of type 
Object'Class would cause a compilation 
error, for Object types do not have an 
Offset field. 

Ray Blaak 
blaak@mda.ca 


Prime Time Again 

Dear DDJ, 

First, may I congratulate DDJ on the 20th 
anniversary of what must be the best pro- 
gramming magazine on the market. 

I particularly enjoyed the September 1995 
issue, not only for the interesting articles 
(including the one on animation, a subject 
I will explore in the not-too-distant future), 
but also for the gems that appear in the 
mailbag. The letter I’m thinking of in par- 
ticular is that from Dwight Keeve about 
prime numbers. He is right to point out 
that Michael Swaine got his numbering 
wrong, but, as Daniel Pfeffer pointed out 
in his January 1996 letter, Keeve’s alterna- 
tive is wrong too —57 is not a prime num- 
ber because it is divisible by three. 

As a nonmathematician, I don’t claim 
any special expertise in this respect. How- 
ever, I have found that the “ABC” rule 
serves me well in programming —“Accept 
nothing, Believe nothing, Check every- 
thing.” Consequently, I consulted The 
Mathematical Experience, by Philip J. 
Davis and Reuben Hersh (Houghton Mif- 


10 


flin, 1982). On page 211, the authors set 
out the first 2500 prime numbers in a 
handy table. The extract in Table 1 shows 
the sequence for the first 20. 

In The Hitchhiker’s Guide to the 
Galaxy, the answer to the great ques- 
tion of life, the universe, and everything 
else is said to be 42. This information 
probably has about as much usefulness, 
but I thought it was worth setting the 
record straight. 

Maurice Arnold 
Victoria, Australia 


Patented Passwords 

Dear DD], 

I'd like to make two points regarding the 
“Algorithm Alley” column “Password 
Generation by Bloom Filters,” by William 
Stallings (DD/J, August 1994). First, the 
title is incorrect. The article describes 
how to use Bloom filters to constrain the 
user’s choice of passwords, but not to 
generate the password. Secondly, read- 
ers should be aware of U.S. patent 
5204,966 issued in 1993 to Digital Equip- 
ment Corp., with myself and Jerry Le- 
ichter (leichter@lrw .com) as inventors. 
DEC also applied for a patent in sever- 
al other countries. 

That patent, “a method for constraining 
the selection of passwords,” covers sys- 
tems such as the one described in Mr. 
Stallings’ article. 

David Wittenberg 
dkw@cs.brandeis.edu 


A Popular Algorithm 

Dear DD/J, 

The popularity algorithm for color quan- 
tization discussed in “The Popularity Al- 
gorithm,” by Dean Clark (“Algorithm Al- 
ley” DDjJ, July 1995) is of historical interest, 
but other algorithms, such as the medi- 
an-cut algorithm (Heckbert, SIGGRAPH 
’82) are just as fast, only slightly harder 
to implement, and produce better pic- 
tures. As I wrote in my 1982 paper, the 
popularity algorithm does a good job on 
many pictures, but performs poorly on 
pictures with a wide range of colors or 
when quantizing to a small number of 
colors (< 50, say). The visible flaws might 
be insignificant on many synthetic images 
of the type displayed in Clark’s article, 


type Object is tagged record 
Positions, 


Pos: 
end record; 


type Line is new Object with 
record 
Offset : Size;:-@ 


end record; 





Example 1: Ada 95 classes. 





but they can be very objectionable on real 
images. Also, it is well known that dither- 
ing can improve the appearance of quan- 
tized pictures dramatically — a fact Clark 
didn’t mention. 

The implementations described by my- 
self and others use hashing techniques, 
lookup tables, and other data structures 
that speed up histogram collection and 
nearest-neighbor finding by an order of 
magnitude (see http://www.cs.cmu.edu/ 
~ph). My 1982 implementation of the 
median-cut algorithm could quantize a 
640x480 picture in 60 seconds on a 1-MIPS 
VAX 780; current workstations can run the 
same algorithm in just a few seconds. 
Paul Heckbert 
Carnegie Mellon University 
Pittsburgh, Pennsylvania 
ph@cs.cmu.edu 


Majority Rule 

Dear DDJ, 

What I have to say has nothing to do with 
algorithms or paradigms, or even com- 
puters. When John Travis, whom I don’t 
know at all, says (as quoted in Jonathan 
Erickson’s November 1995 “Editorial”) “I 
can't believe that we are going to let a ma- 
jority of the people decide what's best for 
this state,” he is actually a bit right. The 
majority of a given population rarely has 
a chance to objectively focus on a political 
subject. Nor is it in the layman’s interest. 
Politicians have an obligation to provide 
the public with information allowing it to 
form an opinion without having to know 
the deepest truth. The problem is then that 
politicians have learned to use this to 
seduce the public and form sentimental 
opinions in their own favor. That is why 
the majority can actually become danger- 
ous. A singer once sang: “Are the many 
the brightest or are they merely more than 
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Table 1: Prime time again. 
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It’s the Intel Pentiume Pro processor. And it’s the brains behind some of 
the most powerful new workstations available. 


Whether you’re creating 3-D graphics for a hot new Web site or authoring a 
multimedia title, designing with CAD applications or developing new software, 
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Intel’s Pentium Pro processor delivers the ©) performance you need. 
The Intel Pentium Pro processor. It’s the € brightest idea to hit work- 


stations in a long time. For more information ¥ visit our Web site at 
http://www.intel.com/ ij The Computer In 


©1995 Intel Corporation 





Class Libraries 
for Real-Time & 
Charting Graphics 


C/C++ AND MFC DEVELOPMENT TOOLS FOR 
WINbows GRAPHICS APPLICATIONS 





Charting Tools and Real-Time Graphics Tools for WindoWS sss 

The Charting Tools for Windows support a wide variety of chart types Real-time graphs derived from 
used in scientific and business applications, including line plots, area plots, ©5°" ollView and CFormView classes are 
bar graphs, scatter plots, group plots, high-low-close plots and pie charts. ASCE aE UEETAN CHES RENEE 
Prices start at $300. a 

The Real-Time Graphics Tools for Windows create dynamic graphical 
displays for use in applications such as network monitoring, scientific and 
medical instrumentation, process control, and financial market displays. 
Graph types include: scrolling graphs, sweep graphs, logic graphs, annun- 
ciators, xy plots, dynamic text, dynamic bar graphs, and meters. Also 
supported are customizable LED controls, buttons, scroll bars and check 
boxes. The Real-Time Graphics Tools include all of the Charting Tools 
functionality. Prices start at $600. 

Both products support development of 16-bit and 32-bit applications for 
Windows 3.1, Windows NT, Win32s and Windows 95. They are targeted at 
C/C++ programmers who prefer traditional Windows API style program- 
ming. Source code is sold separately. If you want to program using MFC, 
purchase one of these products and the Graphics Class Libraries for MFC 
described below. 

Visual Basic and Delphi versions of the Charting Tools and Real-Time 
Graphics Tools for Windows are also available. Call for details. 
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Graphics Class Libraries for MFC 

MFC-based class libraries are available as an add-on product for our 
Charting Tools and Real-Time Graphics Tools for Windows. The Quinn- 
Curtis Graphics Class Libraries for MFC are an extension to MFC, inte- 
grating our tools with the Document/ View architecture. This library We sienaee, ae, Rennie a 
includes classes for both the Charting Tools and Real-Time Graphics Tools. _,,,;,, # print preview. 
It provides a convenient object-oriented interface that significantly reduces 
the effort needed to program graphics applications. With these libraries 
you can build graphs that inherit all of the behavior of CWnd, CView, 
CScrollView, and CFormView classes, including print preview. The cost of 
the Quinn-Curtis Graphics Class Libraries for MFC is $200. The full source 
for the class library is included. 





Free Demo Disk and Catalog ' ee ee 
Call, FAX or write for a free catalog and demo disk. Product information | % = r= or re 
and demos can also be downloaded from our WWW, FTP and BBS sites. 





Combine real- aie graphs and dialog 
Order Now! controls using CFormView. 
Call: 617/449-6155 Fax: 617/449-6109 


30-Day Money-Back Guarantee ! 


Quinn-Curtis, Inc. 
WWW sihttp://www.quinn-curtis.com/~quinn/ 


FTP at ftp.webcom.com in /pub/quinn/demofiles 35 HIGHLAND CIRCLE 
BBS 617/449-4783 NEEDHAM, MASSACHUSETTS 02194 USA 


Windows and Visual Basic are registered trademarks of Microsoft Corp. All other products are trademarks or registered trademarks of their respoective owners. 





(continued from page 10) 

the few?” (The translation doesn’t do him 
justice, I’m afraid.) 

Thomas Honore Nielsen 

Esbjerg Handelsskole, Denmark 
<thn.cls@pip.dknet.dk> 


Online Educational Alternatives 
Dear DDJ, 

Thanks for mentioning the University of 
Missouri’s Center for Independent Study 
in the “Programmer’s Bookshelf” (DDJ, 
September 1994) on nontraditional edu- 
cation alternatives. 

In case someone asks about our BBS 
and examinations, some additional infor- 
mation might be useful. The BBS at the 
end of our 800 number for computer- 
assisted learning (CALS) is designed to re- 
spond only to students sending in a CALS 
lesson. The program will accept their an- 
swers to the questions given at the end of 
a lesson, and send back the professor’s 
responses to each incorrect answer. 

Students wishing to send in lessons for 
courses which are not CALS (for exam- 
ple, writing courses) have other alterna- 
tives, including fax and e-mail. E-mail 
over the Internet will handle courses 
which require only the basic ASCII char- 
acter set. Many courses can be handled 


this way, but students should inquire 
about electronic options available for par- 
ticular courses. The e-mail address for 
those questions is independ@ext.mis- 
souri.edu. The URL is http://indepstudy 
.ext.missouri.edu/. 

Exams can be requested by e-mail, but 
must be sent via U.S. Postal Service to an 


I can’t believe that 
we are going to let a 
majority of the 
people decide 
what’s best for this 
State 
approved examination site where they can 
be proctored and returned to the Center 

for grading. 
Incidentally, the student in Germany fin- 


ished his course in technical writing in 
good time: He used ftp to send fully for- 


Introducing Track Record’ 2.0, a new kind of 
tool from the original developers of BRIEF * 


Take control 
of your software 
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projects! 


Developing software means juggling 
hundreds of details. Let just one of 
them fall through the cracks, and 
you're in for headaches. Wouldn't it 
be great if you had a tool that let you 
take control of all that information? 
Now you do. Track Record® 
is the first and only application 
designed to help you keep track of 
practically everything relating to your 
work — from bugs to beta sites. It’s a 
whole new kind of productivity tool 
for Microsoft Windows, designed 
specifically for software developers. 


» Track Record lets you quickly and 
easily plan tasks, store and retrieve 
information and keep a detailed 
history of who did what, when. 


e Track Record dynamically displays 
information about your software pro- 
jects as they change, so you're always 
up-to-date. 


* Track Record is ready to use right 
out of the box, or configure it to meet 
your personal needs. Use it individu- 
ally, or on a network to keep your 
entire workgroup on track! 


Track Record is a registered trademark of UnderWare, Inc. BRIEF is a registered trademark of Borland International. 
UnderWare, Inc., 321 Columbus Avenue, Boston, MA 02116 USA 
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matted papers to his professor via the Cen- 
ter, and comments were returned to him 
the same way or by e-mail. He was very 
pleased at the speed it permitted and the 
savings in postage and mailing expense. 
We have also had several professors who 
were writing courses while they were in 
Europe sending their manuscripts back 
and forth via the Internet. 

Dale Huffington 

University of Missouri 

Columbia, Missouri 

http://www .missouri.edu/~dldcwww/ 


Generating Sequential Keys 
Dear DD/J, 
The December 1995 “Algorithm Alley” col- 
umn by Gene Callahan entitled “Generat- 
ing Sequential Keys in an Arbitrary Radix” 
reminded me of a problem posed in an 
introductory Pascal course several years 
ago: The state needs to issue license plates; 
provide a function which, given a license 
number “AAZ 999” (for a complex exam- 
ple), returns the next in sequence, “ABA 
000.” A student in the course worked for 
a client of mine; I provided a solution 
(with the explicit design goal that the pro- 
gram could in no way be regarded as the 
output of a first-year student) that used 
(continued on page 10) 


“If you’re a software developer whose 
system for tracking bugs and scheduling 
appointments is to scribble them on scraps 
of paper, then Track Record is for you.” 

— Richard Hale Shaw, PC Magazine, January 11, 1994 


“Track Record is clearly the technology 
leader — the most flexible and sophisticat- 
ed of the bug trackers.” 

— Dave Duchesneau, Data-Based Advisor, June 1995 


“Track Record, from UnderWare, 

whose authors wrote BRIEF, is one of the 
most impressive pieces of software I’ve 
ever used.” 

— Tom Swan, PC Techniques, April/May 1994 


[full reprints available] 


ORDER NOW FOR JuST $195 
FREE GIFT iF YOU MENTION THIS AD 
Risk-free, 60-day money-back guarantee! 
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WinWidgets 3.0 


Intelligent Custom Controls 
for Windows 


WinWidgets is the definitive set of controls you need in CclPinedee 
your toolbox. For one low price you get a complete set of [Arment | af 
interface elements including a Grid and Spreadsheet, 

Tabbed Dialog, Spin Control, Masked Edit, Picture Button, 

Status Bar, Tool Bar, List Box, Combo Box and much 

more. The power of WinWidgets will simplify your devel- 

opment efforts with features such as input validation, ODBC 

database connections and powerful data handling. You can 

include WinWidgets controls with all popular Windows 

development tools including Visual Basic, Visual C++ 

and Borland’s Resource Workshop. WinWidgets supports 

both 16- and 32-bit environments to allow you to develop 

tomorrow’s applications today. 


Here’s just a sampling of the “widgets” you’ll get: 
¢ A Spreadsheet control with edit, check box and combo box cells, that features 100+ 
built-in functions, auto/manual recalculation, and complete control of cell properties 
* A Tab control with unlimited number of auto-sized tabs and custom colors/fonts 
¢ A Grid control with edit-in-place or edit-in-toolbar, resizeable rows/cols, virtual memory 
allowing millions of records, combo box and masked edit fields, special “list box” mode 
* A masked edit control with hundreds of formatting options such as 
“Mmm d, yyyy” and “$#,##0.00”, 
automatic and custom input 
validation, and use of international 
system settings 
¢ List box and Combo box controls 
¢ Buttons including 3D RadioButtons, 
CheckBoxes, GroupPushButton with 
Support for bitmaps and icons 
¢ Frame/Picture control with 3D look 
* Spin Control with support for inte- 
gers, floats, dates and times as well as owner-defined minimum, maximum and 
increment settings 


WinWidgets/VBX 


WinWidgets++ 
WinWidgets/32 
WinWidgets Source Edition 
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FEBRUARY’s H 

SELLERS... 
We feature a huge sele 
of great products for 
programmers—from a 
leading publishers—inc 
the hot sellers feature: 


Paradise No. 


Blinker 4.0 
BIB403100-FK 


ButtonMaker 
FABMW3100-FK 


C++ Views 
ISCVW3100-FK 


Cypress Enable 
CSWE23100-FK 


First Impression 
VTFIO3100-FK 


ForeHELP 
FRFFH3100-FK 


InstallShield3 
$T9513100-FK 


MemCheck Debugger 
SWMCW3100-FK 


MKS Source Integrity 
MKSID3100-FK 


OLETools 
MHOLT3100-FK 


Track Record 
UWTR3100-FK 


WinWidgets XTable 
LPWNXT310-FK 


$589 
$129 
$329 
$149 
$169 


$249 


Call for shipping charges/return 
policy. Prices subject to change 
without notice. 


RoboHELP® 95 
by Blue Sky® Software 
Award-winning RoboHELP 95 guides 
you through the entire process of 
creating Help systems for Windows 
3.x, Windows 95, and Windows NT! 
Full support of ALL Windows Help 
features including Windows 95 con- 
tents tabs, secondary windows, 
authorable buttons, and all the new 
macros; plus ROoboHELP 95 gives you the power and ease of 
use of Microsoft Word. RoboHELP 95 saves you time—it’s 
fast, has instant test mode, and rapidly converts existing 
documentation into a Help system or vice-versa. 


Discount Price: $439 
Paradise No. BSR953100-FK 






MS Visual C++ 4.0 


by Microsoft Corporation 
Combining 32-bit Windows technology 
and a productive environment designed 
to boost performance. Get the latest 
version of Visual C++, plus three more 
releases during the year delivered 
automatically to your desktop. All the 
development tools and information 
you'll need to create applications for 
Windows 95 and Windows NT. 
Paradise No 
Visual C++ Subscription 


MSVC4S888-FK 
Upgrade Subscription 


MSUVCS88-FK 


* Price after $50 manufacturer’s rebate. 


Discount Price 


$469 


Wise Installation 

by Great Lakes Business Solutions 
The Wise Installation System 
creates professional 
installations for Windows, 
Windows NT, and 

Windows 95 all with a single 
installation script. The Wise 
Installation System includes 
both |6- and 32-bit versions of 
the integrated development 
environment. Wise includes all 
of the standard installation features plus: custom 


dialog/graphic editors; CD-ROM/Network installations; multi- 


lingual support; and full Windows 95 install requirements. 
Discount Price: $179 
Paradise No. GLISW3100-FK 


c-tree Plus® 

by FairCom 

DOS * WINDOWS « NT « UNIX * 
OS/2 * SUN * RS6000 * HP9000 
MAC * QNX * BANYAN « SCO. 
This well known, highly portable 
data management package has 
become established as the tool of 
choice for commercial development. 
Offering unprecedented data con- 
trol, choose from direct low level 
access, ISAM level, or SQL access 
with the FairCom Server. Single User, Multi User, or optional 
Client/Server, ANSI Standard. Full Source. No Royalties. 


Discount Price: $769 
Paradise No. FACT+3100-FK 
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WinHelp Office™ 95 
by Blue Sky*® Software 
WinHelp Office 95 is a suite 

of tools to help Windows 
developers create professional, 
full-featured Help systems for 
Windows 3.x, Windows 95, 
and Windows NT—all in one 
box! WinHelp Office is power- 
packed with the award-winning 
RoboHELP, WinHelp Video 
Tool Kit, WinHelp HyperViewer, Mastering WinHelp, 

and the Moving to WinHelp 95 Kit. Also includes SmartHelp 
OLE Control. 


Discount Price: $699 
Paradise No. BKWHO3100-FK 























































SPF/Win v1.0 
by Command Technology 


Corporation 

SPF/Win provides real ISPF-style 
editing and file management power 
for PC application development in 

a native Windows environment 
(Win3.x, Win95, Win/NT). Drag and 
drop, configurable button bar, REXX 
macro interface, SUPERC file 
comparison, syntax colorization for 
languages such as C, COBOL and 
REXX, Micro Focus integration, and more. On-line 
documentation only. 


Discount Price: $149 
Paradise No. CTSPW3100-FK 
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Animated Widgets 
by ProgTools 
Thousands of frames of 
professional, true animation 
pictorially represent com- 
puter tasks. Pages flip past a 
book to simulate reading, a 
hand holding a pencil writes 
into a notepad, a cartoon 
face with moving lips dis- 
plays help text, exploding bombs, fireworks, arrows, on/off 
switches and many more. Very easy to use. Royalty-free dis- 
tribution. Unique compression algorithm. Very fast. Allows 
other processing during animation. Available for C/C++ and 
Visual Basic. Unconditional 30-day money-back guarantee. 


Discount Price: $145 
Paradise No. PTABV3100-FK 
















and popup voice 
can show it off ? 











Help Magician Pro 95 
by Software Interphase 

The popular Help Magician a 
Pro 95 includes everything 
you need to create, edit, and 
simultaneously test great- 
looking help files within a 
WYSIWYG simulation envi- 
ronment, without requiring 
Microsoft Word. It’s like 
working inside of WinHelp! 
The new interactive Help Wizard guides anyone through 
step-by-step creation of professional help files. Supports 
workgroup development and ALL WinHelp features in all 
versions of Windows. Highly recommended! 


Discount Price: $199 
Paradise No. SWHM953100-FK 














Moving to 

WinHelp °95" 

by Blue Sky® Software 

The Moving to WinHelp ’95™ Kit 
automatically converts your 
Windows 3.x Help systems to 
Windows 95 Help systems. This kit 
automatically adds Windows 95 
features to your Help systems and 
updates your source files. Works 
with all Help systems whether they were produced 

manually or with a development tool. Also includes Mastering 
Windows 95 Helb—The Official Book for Help Authoring. 

Highly recommended! 


Discount Price: $79 
Paradise No. BKMWH3100-FK 
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Adrem Project 


ToolBox’ 
by Adrem 


Project Toolbox™, with patented 
REStechnology”, is the only soft- 
ware that can save your projects’ 
time and money. It’s an add-on to 
Microsoft Project that empowers 
you to: “reverse engineer” changes 
rapidly; assign “multiple skills” to 
resources for improved efficiency; and optimally schedule 
resources. Toolbox provides “what-if” capabilities to 
project managers. 


Discount Price: $149* 
Paradise No. ARBPT3100-FK 


* With the purchase of MS Project. 


















Codewright 4.0 


by Premia 
More powerful than ever with 
the new API Assistant! 
Prevents bugs before they 
happen; has Button Links 

to non-text files, and Direct 
Access version control 
interface. Multi-FKle search and replace, help topic scanner, 
file differencing and merging, are real time-savers. 














Discount Price: $199 
Paradise No. PCCW43100-FK 


Dan Bricklin’s® 
demo-it!” 
The demo builder for Windows® 


by Lifeboat Publishing 


Need to demonstrate what your soft- 
ware can do? With demo-it! you can 
create fully interactive or self-running 
demos. demo-it! features rich text sup- 
port, is completely WYSIWYG, 
launches internal programs, supports 
variables & conditions, has enhanced 
special effects and works great on 
CD-ROMs, Internet and on-line services. Freely distributable 
170K runtime player. 


Discount Price: $299 
Paradise No. LIDDW3100-FK 
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Visual SlickEdit® 
by Micro Edge 

Acclaimed as the most configurable 
editor available, Visual SlickEdit has 
the features and power you crave. 
Save time using CUA, BRIEF, Emacs, 
and VI emulations. Program effi- 
ciently using project management, 
SmartPaste™, syntax color-coding, 
and built-in dialog editor. With 
numerous awards, Visual SlickEdit 


has become the standard editor 
of the 90’s. 


Discount Price: $279 
Paradise No. MEBSE3100-FK 


















































We feature all of the 
best products from top 
manufacturer’s at the 
lowest prices! 


Call us to find out how you 
can receive more information 
on featured products through 

our exclusive FAXcetera 
service. Have information 
sent instantly, 24 hours a day! 


Dan Bricklin’s® timeLOCK" 
by Lifeboat Publishing 


Be among the first to use Dan 
Bricklin’s timeLOCK, the first 
commercially available developer’s 
toolkit that creates fully functional 
“timeLOCKed” versions of 
Windows® software. timeLOCK 
lets users try your software—for 
a specified period of time that you 
set. Your demos will be secure 
when you distribute “trialware” instead of “shareware.” You 
can control who uses your software—and when they use it. 


Discount Price: $460 
Paradise No. LIDTK3100-FK 


You'll love our 

service, too! 
A personal guarantee: 
“If you’re not happy, we're 
not happy. You have my 
personal guarantee that 
we'll provide you with out- 
standing products, support 
and service.’ 


—Roger Paradis, 


President & CEO, 
Programmer’s Paradise, Inc. 
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Product of the Month 
ProtoView Visual 
Help Builder 


by ProtoView Development 
The ProtoView Visual Help Builder is 
a RAD help development environ- 
ment. Developers can document an 
application, whether they have that 
application’s “source” programs or 
not. With a few clicks of the mouse, 
ProtoView Visual Help Builder 
captures every dialog box, menu and 
control field of an application and 
creates a full blown help system. 


Discount Price: $380 
Paradise No. PDVHB8888-FK 


dtSearch® 4.0 & 
TextBridge® OCR Bundle 
by DT Software, Inc. & Xerox® 


Instantly search your file cabinet! 

Bundle integrates award-winning 
TextBridge OCR with dtSearch “industrial- 
strength text-searching.”—PC Magazine. 
Includes natural language, fuzzy, phonic, 
and/or/not, proximity, wildcard, field & 
numeric range searches. Searches with or 
without search index. (Indexes up to 10 
MB/min; indexed searches usually under 
a second.) Displays files as text or images. 
Supports multiple file types. 


Discount Price: $239 
Paradise No. DTSTB3100-FK 
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The developer's best source 
for software under the sun! 


ORDER NOW 
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free catalog! 
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(continued from page 12) 

the (VAX) Pascal schema construct to 
make a numeric string. The arguments to 
the schema definition were a set of legal 
characters and a string length. 

The increment() operation on this 
schema returned not only the incre- 
mented string, but a carry flag to indi- 
cate overflow (as when “999” was 
wrapped to “000”). Thus, the LicensePlate 
type contained two NumericStrings of 
length 3, one based on the set (‘A‘..'Z'), 
the other on the set ('0'..'9'). The 
nextPlate() operation would increment 
the numeric string, and then— on a car- 
ry out of this operation— increment the 
alphabetic string. 

I’m sure the program met its design goal: 


The student didn’t dare turn it in as her 
own work. I wonder now how I would 
solve the problem, had it been required 
for a C or C++ class. The capabilities of 


The Macintosh 
operating system 
has had a solid 
TCP/IP for years 





the language shape the design, certainly: 
I'd probably have several hundred lines of 
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C++ code implementing OrderedSet<char>, 
NumericString<OrderedSet<char>, and so 
forth. 

Ron Lusk 

Blue Bell, Pennsylvania 
ron.lusk@phh.mts.dec.com 


Never Mind the Bullocks... 

Dear DDJ, 

Regrettably, bassists may die, but their 
estates live on. By simply naming his mu- 
sic program “Mingus” or “Pastorius,” Al 
Stevens is getting no guarantee of safe- 
ty. (See “C Programming,” DD/, Septem- 
ber 1995.) Fortunately, there is one name 
meeting your criteria which should be 
free of any such concerns, with the added 
bonus of suitably reflecting the likely 
quality of the output during the inevitable 
debugging stages—Vicious. 

Mike Ryan 

Virtuoso Software 
http://world.std.com/~deeryan/virtu- 
oso. html 


Mac Can Do 

Dear DDJ, 

I enjoyed the article “Networking Objects 
with CORBA,” by Mark Betz (DDJ, Novem- 
ber 1995). However, Mark’s statement 
about major operating-system vendors’ 
support of TCP/IP was incomplete. He did 
not mention that the Macintosh operating 
system has had a solid TCP/IP stack for 
years and that it has-been included with 
OS releases since last year (System 7.5). 
Justin Souter 

Justin_Souter@artlogic.com 


Mark replies: Thanks Justin, that’s a very 
good point. I admit that I simply failed to 
consider the Macintosh when I made the 
statement. We do have Macs where I work, 
and they are on our TCP/IP domain along 
with everything else. 


Go Figure 

Dear DD], 

Thanks for publishing the article “Data 
Models, CASE Tools, and Client/Server De- 
velopment,” by Tim Wittenburg (DDJ, 
November 1995). However, it appears that 
the illustrations for Figures 1 and 2 on 
page 92 were reversed. 

Jim Rommens 
tktfa31%ezmail@pyibm1.cc.bellcore.com 


DDJ 


DDJ welcomes your comments and sug- 
gestions. Send letters to DDJ, 411 Borel 
Ave., San Mateo, CA 94402-3522. We can 
also be reached via editors@ddj.com, 
76 704.50@compuserve.com, and by fax 
at 415-358-9749. Please state your name 
and address. DDJ reserves the right to edit 
letters for length and/or content. 


Dr. Dobb’s Journal, February 1996 








(P™, Come to the 1996 IBM International Technical T-shirts. For enrollment information and program brochure, 


recta Interchange, April 22-26 in Nashville, TN. call 1 800 872-7109 (U.S. & Canada) or | 617 893-2056 
i" os wy There's a lot to experience: Insights into IBM's (Outside N. America). Or visit our Web site at http://www. 
latest software strategies. Over 300 unique elective austin.ibm.com/developer/conferences/ ti_96 for details. 


sessions, including App Development, Network-Centric and 
Client/Server Computing. ‘Tips and techniques for building 
a competitive advantage. More than 200 exhibitors. Free 


Developer Connection software. And, of course, some nifty Solutions for a small planet” 


The IBM home page is located at http://www.ibm.com. IBM, AS/400, AIX, OS/2 and S/390 are registered trademarks and Solutions for 
a small planet is a trademark of International Business Machines Corporation. ©1995 IBM Corp. All rights reserved. 


Proposing a 
Standard Web API 





Short circuiting the API wars 





Michael Doyle, Cheong Ang, and David Martin 


he World Wide Web has matured from a relatively limited 

system for passive viewing of hypermedia-based documents 

into a robust framework for interactive application devel- 

opment and delivery. Much of this progress is due to the 
development of embedded executable content, also known as 
“inline Web applets,” which allow Web pages to become full- 
blown, compound-document-based application environments. 
The first Web-based applets resulted from research begun in the 
late 1980s to find a low-cost way to provide widespread access 
for scientists and educators to remote, supercomputer-based vi- 
sualization systems. 


The Visible Human Project 

In the late 1980s, the National Library of Medicine began a pro- 
ject to create a “standard” database of human anatomy. This 
“Visible Human Project” was to comprise over 30 GB of volume 
data on both male and female adult human anatomical struc- 
tures. It was one of the original Grand Challenge projects in the 
federal High-Performance Computing and Communications ini- 
tiative, the brainchild of then Senator Al Gore. As a member of 
the scientific advisory board for this project, one of us (Michael 
Doyle) became interested in the software issues involved in 
working with such a large database of the most detailed image 
information on human anatomical structure yet available. His 
group in the Biomedical Visualization Lab (BVL) at the Univer- 
sity of Illinois at Chicago realized at the time that much research 
would have to be done to make such a vast resource both func- 
tional and accessible to scientists all around the world. 

Until that time, medical visualization systems were designed 
to work on 3-D datasets in the 15-30 MB range, as produced 
by the typical CT or MRI scanner. High-end graphics workstations 
had adequate memory capacity and processor power to allow 
good interactive visualization and analysis of these routine 





The authors are cofounders of Eolas Technologies Inc. and can 
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datasets. The Visible Human data, however, presented an en- 
tirely different set of problems. To allow widespread access to 
an interactive visualization system based upon such a large body 
of data would require the combined computational power of 
several supercomputers, something not normally found in the 
typical biomedical scientist's lab budget. 

Doyle’s BVL group immediately began to work on solving the 
information-science problems related to both allowing interactive 
control of such data and distributing access to the system to sci- 
entists anywhere on the Internet. Our goal was to provide ubiq- 
uitous access to the system, allowing any user connected to the 
Internet to effectively use the system from inexpensive machines, 
regardless of platform or operating system. 


The Promise of the Web 

We saw Mosaic for the first time when Larry Smarr, director of 
the National Center for Supercomputing Applications, demon- 
strated it at an NSF site visit at BVL in early 1993. We became 
immediately intrigued with the potential for Mosaic to act as 
the front end to the online visualization resource we had been 
designing. Immediately after Michael Doyle left the University 
of Illinois to take the position of director of the academic com- 
puting center at the University of California, San Francisco, we 
began enhancing Mosaic to integrate it with our system. We 
designed and implemented an API for embedded inline ap- 
plets that allowed a Web page to act as a “container” docu- 
ment for a fully interactive remote-visualization application, al- 
lowing real-time volume rendering and analysis of huge 
collections of 3-D biomedical volume data, where most of the 
computation was performed by powerful remote visualization 
engines. Using our enhanced version of Mosaic, later dubbed 
“WebRouser,” a scientist using a low-end workstation could ex- 
ploit computational power far beyond anything that could be 
found in one location. 

This work was shown to several groups in 1993, including 
many that were later involved in projects to add APIs and app- 
lets to Web browsers at places such as NCSA, Netscape, and 
Sun. Realizing our group’s work enabled the transformation of 
the Web into a robust platform for the development and de- 
ployment of any type of interactive application, in 1994 the Uni- 
versity of California filed a U.S. patent application covering em- 
bedded program objects in distributed hypermedia documents. 
Eolas Technologies was then founded by the inventors to pro- 
mote widespread commercialization and further development of 
the technology. 
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Enhancing the Web 

Once the concept of the Web as an environment for interac- 
tive applications was initiated, the question was how to fur- 
ther develop it. Toward the end of 1993, we discussed the 
relative merits of building an interpreted language, such as 
Basic or Tcl, directly into the browser versus enhancing 
browsers through a “plug-in” API. We chose the API approach, 
believing that the best way to add language support would 
be by adding interpreters as external inline plug-in applets, 
which we called “Weblet applications.” This would enable us 
to add a new language or other feature merely by develop- 
ing a new Weblet application, without having to reengineer 
the browser itself. 

Figure 1 is a Weblet-based version of the public-domain RAS- 
MOL visualization program that lets users view, analyze, and vi- 
sualize a 3-D protein structure from within the Web page. A sin- 
gle programmer converted the original RASMOL source code into 
Weblet form in only ten hours. 

Some time later, both limited API support, such as NCSA’s 
CCI, and embedded-language support, such as Java, began to 
appear in various Web browsers; the <EMBED...> tag (which 
we first implemented in mid-1993) appeared in beta versions 
of Netscape’s product by summer of 1995. Still, it wasn’t until 
October of 1995 that the Netscape implementation began to 
approach the functionality of <EMBED...> used in WebRouser. 
The enormous effect of these developments in accelerating the 
commercialization of the Internet industry prompted us to re- 
lease the first (free-for-noncommercial-use) distribution ver- 
sion of WebRouser for UNIX platforms in September 1995 
(http://www.eolas.com/eolas/webrouse/). 





The WebRouser Approach 

Our general philosophy with WebRouser was to allow en- 
hancement of the browser's functionality through object-oriented, 
modular application components that conform to a standard 
API, rather than turning the browser into a monolithic applica- 
tion with an ever-increasing code base. This encourages Web 
developers to take a document-centric approach to application 
development. The Web page itself becomes the mechanism for 
doing work, through collections of small, efficient Weblet build- 
ing blocks, rather than the menagerie of top-heavy applications 
found on the common desktop PC. 

The first release of WebRouser also included other enhance- 
ments aimed primarily at improving the interactivity of Web 
pages. These included client-side image maps, a document- 
driven button bar, and document-driven modification of the 
browser’s menu tree. 

Client-side image maps are supported through the Polymap 
format. Polymap files are essentially GIF files with polygon and 
URL information stored in the image’s comment fields. To pre- 
vent complex polygon information from bloating the file, all of 
the comment fields are compressed and decompressed using 
the GIF LZW algorithm. Polymap files require no special treat- 
ment of the HTML code. WebRouser autodetects the presence 
of Polymap data when it reads inline GIFs. If a server-side 
(ISMAP) image map points to a Polymap GIF, then WebRouser 
will ignore the ISMAP data and give the Polymap data priority. 
Hotspots are decoded in real time and highlighted as the mouse 
moves over the image, and the associated URL is displayed at 
the bottom of the screen, providing users the same style of in- 
teractivity that hotwords have in HTML text. The Polymap for- 
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mat specification is open and freely available for use. You can 
find the spec at http://www.eolas.com/papers/Papers/Polymap/. 

The <LINK...> and <GROUP...> tags allow Web pages to dy- 
namically customize elements of the browser’s GUI. The LINK 
tag allows the creation of a document-driven button bar imple- 
mented by placing tags in the document header, with the syn- 
tax <LINK ROLE="button label" HREF="bttp://...">. Several of 
these tags in sequence result in buttons below the URL window, 
similar to Navigator’s What’s New or What’s Cool buttons, but 
they are dynamically defined by the page currently being viewed. 
Similarly, the GROUP tag allows the Web page to modify the 
browser's GUI, however, this tag differs by defining a hierar- 


chical menu that reflects an entire tree of Web pages. In Exam- 


ple 1, a typical GROUP menu trigger, the text string “Click here 
to view the WebRouser slide show” appears as a conventional 
anchor on the Web page, but selecting it brings up the 
“slide_1.html” and activates the GROUPS menu option on Web- 
Rouser’s menu bar. Slide Show is the first menu option, with a 
submenu whose options are Slide 1, Slide 2, and Slide 3. This 
allows the user to easily navigate through, for example, the “year, 
issue, article” hierarchy of online magazines. 


The Web API 

Of course, the key feature of WebRouser is the implementation 
of the <EMBED...> tag, through which inline plug-in Weblet 
applications are supported in Web pages. X Window applica- 
tions that conform to the Eolas distributed hypermedia object 
embedding (DHOE) protocol can run— inline and fully inter- 
active — within Web pages in the WebRouser window. WebRouser 
also supports the NCSA common client interface (CCD, which 
allows the Weblet to “drive” the browser application. DHOE and 
CCI collectively make up the Eolas Web API (WAPI) as sup- 
ported in WebRouser. 

WAPI is minimalist, combining the functionality of DHOE and 
CCI to exploit both the efficiency of X-events for communica- 
tion of interaction events and graphic data and the flexibility of 
socket-based messaging for browser remote control and HTML 
rendering of Weblet- generated data. We are currently working 
on a cross-platform API, in the form of an OpenGL-style com- 





Figure 1; Typical Weblet application. 
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mon-function library. The current minimalist WAPI specification 
will allow us greater flexibility in creating a cross-platform API, 
while maintaining compatibility with Weblets developed under 
the UNIX WAPI specification. 

Eolas’ primary objective with respect to the pending Web-ap- 
plet patent is to facilitate the adoption of a standard API for in- 
teractive, Web-based application development, and then to de- 
velop innovative Weblet-based applications for the growing 
Internet software market. For an example of such a Weblet ap- 
plication, see the accompanying text box entitled “WebWish: 
Our Wish is Your Command.” We intend to short circuit the API 
wars brewing between the major Web-browser competitors. In 
addition to creating a universal standard API, we are also insti- 
tuting a mechanism for ensuring continued evolution of the WAPI 
spec on a regular timetable. Royalty-free licenses for browser- 
side implementation of Web applets under the pending patent 
have been offered to the major browser companies, and are in 
various degrees of negotiation. The primary condition of these 
licenses is that each licensee must conform to the WAPI protocol, 
and no other applet-integration protocol. A consortium of Eo- 
las licensees is being formed to set the continuing WAPI speci- 
fication and update it at regular intervals. The widespread ac- 
ceptance of the developing WAPI standard will allow application 
developers to concentrate on the functionality of their applets 
without worrying which Web browser their customers will use. 


Creating a WebRouser Weblet 

WebRouser communicates with Weblet applications through a 
set of messages called the DHOE protocol. DHOE messages are 
relatively short character strings, which allow convenient, effi- 
cient use of existing interprocess-communications mechanisms 
on various platforms. We have implemented DHOE systems on 
several X Window platforms, including IRIX, SunOS, Solaris, 
OS/F 1, Sequent, and Linux. Implementations for both Microsoft 
Windows and Macintosh are planned for release by the end of 
the first quarter of 1996. 

Listing One (listings begin on page 91) is a skeleton program 
for Weblet-based applications that can work with WebRouser. 
The current DHOE protocol defines a set of messages that syn- 
chronize the states on the DHOE clients and DHOE servers. The 
first four messages are used by the server to set up the DHOE 
system at startup, refresh/resize the client, and terminate the sys- 
tem on exit. The rest of the messages are sent by the browser 
client to the data server. They include messages about the client 
drawing-area visibility, and mouse and keyboard events. 

Programming with DHOE involves initializing DHOE by in- 
stalling a message-handling function, registering the DHOE client 
with the DHOE server, and registering various callbacks with 
their corresponding messages. The DHOE client and server may, 
at any time after client/server registration, send messages to each 
other. The messages (see Table 1) are character strings, and may 
be followed by different types of data. DHOE also supports 
buffer sharing (that is, bitmaps and pixmaps) between DHOE 
clients and servers. 

Adding the DHOE mechanism into an existing data handler 
creates a DHOE server. The DHOE library kit consists of pro- 
tocol_lib.h (the declaration file) and protocol_lib.c (the imple- 
mentation file). To follow the Xt programming conventions, the 
DHOE strings are #defined with their Xt equivalents (DHOEkeyUp 


<GROUP ROLE="Slide Show"> 
<LINK ROLE="Slide 1" HREF="slide_1.html"> 
<LINK ROLE="Slide 2" HREF="slide_2.html"> 


<LINK ROLE="Slide 3" HREF="slide 3. htmi"™> 
Click here to view the WebRouser slide show </GROUP> 





Example 1: Typical GROUP menu. 
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(continued from page 20) 
is mapped to XtNkeyUp, and so on). Messages from the DHOE 


server to the DHOE client (for example, external app—hyper- 


media browser) are: 
e XiNrefreshNotify, server updating. 


e XtNpanelStartNotify, server ready. 
° eNO server exiting. 


Table 1: DHOE messages. 
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DHOEserverUpdate 
DHOEserverReady 
DHOEserverExit 
DHOEserverConfigureWin 
DHOEclientAreaShown 
DHOEclientAreaHidden 
DHOEclientAreaDestroy 
DHOEbuttonDown 
DHOEbuttonUp 
DHOEbuttonMove 
DHOEkeyDown 


DHOEkeyUp 
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Messages from the DHOE client to the DHOE server (for ex- 
ample, hypermedia browser external app) are: 


e XtNmapNotify, DHOE area shown. 


¢ XtNunmapNotify, DHOE area hidden. 


Description 


Tells a client to update data. 

Tells a client the server is ready. 

Tells a client the server is exiting. 

Tells a client to resize/reposition 
the DHOE window. 

Tells the server the DHOE area is 
exposed. 

Tells the server the DHOE area is 
being hidden. 

Tells the server the DHOE area is 
being destroyed. 

Sends mouse-pointer coordinates 
to the server on button down. 

Sends mouse-pointer coordinates 
to the server on button up. 

Sends mouse-pointer coordinates 
to the server on button move. 

Sends the corresponding keysym 
to the server on key down. 

Sends the corresponding keysym 
to the server on key up. 
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e XtNexitNotify, DHOE area destroyed. 

¢ XtNbuttonDown, DHOE area button down. 
e XtNbuttonUp, DHOE area button up. 

e XtNbuttonMove, DHOE area button move. 
e XtNkeyDown, DHOE area key down. 

e XtNkeyUp, DHOE area key up. 


You can name these messages differently as long as the 
names are merely aliases of the original DHOE strings. These 
messages are defined in protocol_lib.h, which must be included 
in your program. 

The following DHOE fundamental functions are provided in 
protocol_lib.c: 


¢ void handle_client_msg( Widget w, caddr_t client_data, 
XEvent *event), a function called back by XtAddEvent- 
Handler when it sees a message from the DHOE client (the 
hypermedia browser). To register this function with Xt, your 
program (DHOE server) should call XtAddEventHan- 
dler( Widget app_shell, NoEventMask, True, handle_client_ 
msg, 102);. Here, handle_client_msg will be called with pa- 
rameters w=app_shell, client_data=102, an event pointing 
to an X-event structure generated by Xt when it sees the 
message. The app_shell variable is usually the application 
shell returned by XtInitialize, XtAppInitialize, or XtVa- 
Applnitialize. 





Cross Platform : 
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(continued from page 22) 

° void register_client( Widget w, Display *remote_display);, which 
registers your program with the DHOE client. 

° void register_client_msg_callback(char *msg, void (*func- 
tion_ptr)());, which registers a function to be called back 
when Xt sees a string that matches msg. This function may 
appear anywhere in your program. You do not need to han- 


dle the XtNmapNotify/XtunmapNotify pair because DHOE > 


servers deiconify/iconify when they receive these messages. 
You must specify a “quit” function to shut down your appli- 
cation gracefully on XtNexitNotify. Button- and key-message 
handling are optional. To obtain mouse coordinates, call 
get_mouse(int *x, int *y) for button-handling functions and 
get_keysym(KeySym *keysym) for key-handling functions. 
Keysym is defined by X11 (in keysymdef.h) for cross-platform 
compatibility. 

° void send_client_msg(char *msg, Display *remote_display, 
Window remote_window);, which sends a message with the 
value msg to the DHOE client at a display=remote_display and 
has an X window ID of remote_window. The remote_display 
and remote_window must be provided. This function may ap- 
pear anywhere in the program after register_client. 


A Weblet CAD-File Viewer 

WT is an applet that allows interactive rotation and zooming of 
a 3-D CAD file stored in NASA’s neutral file format (NFF). The 
source code for the sample Weblet application is available elec- 
tronically (see “Availability,” page 3) and at http://www 
.eolas.com/eolas/webrouse/wtsrc.tar.Z. What follows is a brief 
walk-through of the weblet-enhancing sections of the code (il- 
lustrated in the code listing just mentioned as a “simplified sam- 
ple program outline”). 
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1. The outline starts with a typedef'and some global declarations. 
The new type, ApplicationData, defines a structure common to 
all Xt Weblets. Together with the myResources and myOptions stat- 
ic variables, myAppData (which is of type ApplicationData) is used 
with XtGetApplicationResources in main() to extract the command- 
line arguments flagged with win, pixmap, pixmap_width, pix- 
map_height, and datafile. This is how Xt extracts command-line 
arguments and is unnecessary if the program has alternatives to 
decode command-line arguments. The aforementioned global vari- 
ables and XtGetApplicationResources nicely store the information 
ina line such as wt -win 1234 -pixmap 5678 -pixmap_width 400 
- pixmap_height 300 -datafile fname into myAppData. 

2. In main), app_shell is first initialized the Xt way by using 
XtInitialize, which opens a connection to the X server and cre- 
ates a top-level widget. XitGetApplicationResources gets the ap- 
plication resources as in step 1. The next section conveniently 
uses the myAppData.win variable to find out if the Weblet should 
run as a DHOE server or a stand-alone program. For a DHOE 
server, the program adds the handle_client_msg function from 
the DHOE implementation, protocol_lib.c, as the handler of the 
X client message event. The subsequent lines call three more 
DHOE functions: register_client, to initiate a handshake with the 
DHOE client; register_client_msg_callback, to register myQuit() 
as the callback function of the message XtNexitNotify; and 
send_client_msg, to send a XtNpanelStartNotify message, telling 
the DHOE client that the server is ready. The program then en- 
ters the conventional XtMainLoop(). 

3. Two more functions must be modified. The drawing rou- 
tine (myDraw) needs to copy the drawn picture (myPixmap in 
this case) onto myAppData.pixmap, the client’s pixmap. The func- 
tion then should send an XtNrefreshNotify message to the client, 
informing it of the change. The myQuit() function registered in 
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(continued from page 24) 
main() needs to send an XtNpanelExitNotify message to the 
client, telling the client that the server is terminated. 


This Weblet can be tested by putting it in your path and point- 
ing your copy of WebRouser to http://www.eolas.com/eolas/ 
webrouse/office. htm. 


The Eolas Web OS 
In addition to the WebWish applet described in the text box, a 
Java interpreter Weblet application is planned for release by the 
end of March 1996. Java is a compiled language that produces bi- 
naries for a “virtual machine.” The binaries are downloaded to 
the client and run on virtual-machine emulators that run on Mac- 
intosh, Windows, and UNIX platforms. Java applications tend to 
be smaller and more efficient than WebWish interpreted code, 
but they are far more difficult to develop. Eolas is developing a 
virtual operating system, the Web OS (planned for release late in 
1996) that will allow far more robust, compact, and efficient com- 
piled applets to be developed than is possible with Java. The Web 
OS is key to Eolas’ long-term goal to transform the Web into a 
robust, document-centric, distributed-component application en- 
vironment. It is a real-time, preemptive multitasking, multithreaded, 
object-oriented operating system that will run efficiently on low- 
end platforms, even on 80286-based systems and handheld PDAs. 
The Web OS can run within Windows, Macintosh, and UNIX 
environments, or in stand-alone mode on machines with no pre- 
installed operating system. It supports dynamic memory man- 
agement and linked libraries, and is both graphical and object ori- 
ented at the OS level. The OS kernel includes fully defined object 
classes, inheritance, and direct messaging. The OS includes sev- 


oted replies, MIME at 
d-drop filing, printing an 
he world at your fingertips. 
‘Internet Edition — 
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eral building-block objects that allow sophisticated applications — 
WYSIWYG word processors, spreadsheets, databases, e-mail sys- 
tems, and the like— to be developed with a minimum of code. 
These applications are created primarily by subclassing and com- 
bining various Web OS component objects. Since new applica- 
tions are created by defining differences and additions to the con- 
stituent objects, this results in tiny, robust, efficient binaries that 
optimize both bandwidth usage and server storage requirements. 
This platform is so efficient that a complete WYSIWYG word pro- 
cessor can be created in less than 5K of compiled code. Appli- 
cations developed for the Web OS are likely to be smaller than 
most of the inline GIF images found on average Web pages today. 

The operating system employs a single imaging model for 
screen, printer, fax, and other output devices; an installable file 
system, for both local and remote file access; direct TCP/IP and 
socket support; distributed objects; and security through public- 
key encryption and “ticket-based” authentication. 

As the Internet pervades more of our work environments, the 
Web OS will allow the Web to become the preferred environment 
for new and innovative productivity, communications, and entertain- 
ment applications for all hardware platforms. The concept of a 
machine-specific operating system will become irrelevant, since 
any application will be available to the average user, regardless 
of hardware platform. Much of the computational load for ap- 
plications will be pushed off to remotely networked computa- 
tional engines, allowing low-cost Web terminals to act as ubig- 
uitous doorways to potentially unlimited computational resources. 
The Web will be your operating system and the Internet will be 
your computer. 

DDJ 
(Listing begins on page 91.) 
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Improving Kermit 
Performance 





A windowing strategy 
makes all the difference 





Tim Kientzle 


_ any people associate Kermit with 
ponderously slow file transfers. 
Conservative encoding, small 
: packets, and, “stop-and-go” half- 
duplex transfers make speed a common 
complaint about the original 1981 proto- 
col. (For a discussion of the original Ker- 
mit protocol, see “Kermit Meets Modula- 
2,” by Brian Anderson, DD/, May 1989.) 

A lot can change in 15 years, however. 
Developers at The Source Telecomputing 
began to experiment with “windowing 
Kermit,” also known as “SuperKermit,” in 
1985. Windowing allows the Kermit sender 
to send multiple packets before expecting 
a reply. The combination of windowing, 
longer packets, and relaxed encoding con- 
straints makes today’s Kermit protocol one 
of the most flexible and best- performing 
file-transfer protocols available. 

Kermit’s windowing approach is clear- 
ly faster than protocols such as XModem 
and YModem, which must wait after each 
packet. What many people don’t realize 
is that under less-than-ideal conditions, 
Kermit’s windowing approach is signifi- 
cantly faster than ZModem, a protocol with 
a well-deserved reputation for fast trans- 
fers over good-quality connections. The 








Tim, a technical editor with DDJ, is the 
author of The Working Programmer’s 
Guide to Serial Protocols (Coriolis, 1995) 
and Internet File Formats (Coriolis, 1995). 
He can be contacted at kientzle@ddj.com. 
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difference lies in how these two protocols 
respond to errors. 

In this article, Pll compare the error- 
handling strategies of a variety of popular 
protocols. I'll then give a brief overview 
of Kermit and describe some simple heur- 
istics ’ve developed to improve the per- 
formance of Kermit’s windowing strategy. 


Error-Handling Strategies 

Most serial and networking protocols use 
a general error-correction strategy called 
“retransmission.” The sender computes an 
error- detecting signature value, such as a 





checksum or cyclic redundancy check 
(CRC), for each block of data and sends 
that signature value with the data. The re- 
ceiver recomputes the signature and com- 
pares it with the value received from the 
sender. If the two values don’t match, the 
receiver asks the sender to retransmit the 
block. 

XModem and YModem use this strate- 
gy in a simple way. The sender sends a 
single packet at a time and waits for a re- 
sponse. This works well if there is no de- 








lay; that is, if each packet arrives imme- 
diately at its destination. In that case, the 
sender sees an instantaneous response to 
each packet, allowing it to maintain an al- 
most continuous flow of data, even when 
there are errors. 

In practice, most connections have de- 
lays. Each sent packet must navigate 
through system I/O buffers, modems, net- 
works, and other obstacles before being 
received. XModem can be slow when 
there are delays; the sender must wait af- 
ter each packet for a complete round-trip 
from the sender to the receiver and back. 
When there are both delays and errors, 
there will be several round-trip delays for 
some packets. 

Because of these delays, many proto- 
cols send several packets before expect- 
ing a response. This allows the sender to 
continue sending while awaiting the re- 
ceiver’s response, with corresponding 
speed gains. However, the price of these 
performance gains is more-complex er- 
ror handling. 

Protocols such as ZModem and UUCP’s 
G protocol allow multiple outstanding 
packets, but attempt to reduce the com- 
plexity by only transferring packets in or- 
der. At any point in time, the receiver only 
accepts the next consecutive packet. If the 
receiver sees the wrong packet (for ex- 
ample, if the packet the receiver expect- 
ed was lost or damaged and it’s now re- 
ceiving a later packet), it will ignore it and 
send an error notification to the sender. 
This simplifies both the receiver and 
sender. However, when an error occurs, 
the two sides must wait for a complete 
round-trip, as the receiver’s error message 
travels back to the sender and the sender 
resends the correct packet. Intervening 
packets are simply discarded. As a result, 
much of the speed advantage of these pro- 
tocols is lost when errors occur. 
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(continued from page 28) 

The most complex approach is “pack- 
et reassembly,” used by TCP (Transmis- 
sion Control Protocol) and Kermit. In this 
approach, the receiver stores each correct 
packet, even if it arrives out of order. The 
name “packet reassembly” comes from the 
process of reassembling the packets into 
the correct order before passing the re- 
ceived data to its destination. If a packet 
is damaged, only that single packet will 
be resent; in ZModem, a number of sub- 
sequent packets may also have to be re- 
peated. When properly implemented, a 


protocol using packet reassembly need 
never wait for a full round-trip, even when 
there are errors. 


Kermit Basics 

Kermit was developed at Columbia Uni- 
versity in 1981 by Frank da Cruz and Bill 
Catchings to provide a way of transferring 
data between a variety of different com- 
puters. Since then, Kermit has been ex- 
tended to support packet reassembly 
(“windowing”), a variety of file attributes, 
crash recovery, character-set translation, 
and other features. Modern Kermit is ef- 


Len Bytes 


Name 


Start-of-packet character, usually Control-A. 


Length 
Sequence 
Packet type. 


Length of remaining fields after encoding, offset by 32. 
Packet sequence number, modulo 64, offset by 32. 


Packet data, prefix encoded. 
Error check of previous four fields. 


Figure 1: Kermit short packet format. 
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ficient and flexible, providing fast trans- 
fers under less-than-ideal conditions. 

In a Kermit transfer, the sender and re- 
ceiver exchange packets of data. Figure 1 
is the original Kermit packet format. An 
important design feature of Kermit is that 
all of the packet overhead — including the 
length, sequence number, and error 
check— is in ASCII form. This allows Ker- 
mit, with the optional eighth-bit encoding, 
to function in situations where only the 
printable ASCII characters can be safely 
transferred. Two additional formats — 
“long” and “extra-long’— support longer 
packets and a separate error check for the 
header; see Figure 2. 

Generally, the Kermit sender sends a 
packet, possibly containing some data, and 
the receiver responds with an Acknowledge 
packet whose data field contains the re- 
sponse. For example, when a file transfer 
begins, the sender sends a Send-Init pack- 
et with an encoded string specifying the 
sender’s capabilities; the receiver’s ac- 
knowledgment specifies the receiver’s ca- 
pabilities. A packet and its response have 
the same sequence number. You can think 
of a Negative Acknowledge packet as a 
request by the receiver for a particular pack- 
et; an idle receiver waiting to see a Send- 
Init will periodically emit Negative Acknowl!- 
edgments with sequence number zero. I'll 
use the term “exchange” to refer to a single 
packet sent by the sender and the receiv- 
er’s corresponding Acknowledge packet. 

A complete transaction starts with a 
Send-Init exchange to establish the com- 
mon capabilities of the sender and re- 
ceiver. Each file transferred requires a File 
exchange to establish the filename, the 
transfer of the actual file data (which I'll 
explain later) and an End-of-File exchange. 
After all files are transferred, a Break ex- 
change terminates the transaction. 

Kermit’s original strategy for transferring 
file data used this exchange mechanism in 
a simple fashion. The sender would send 
a Data packet containing some file data 
and wait for the corresponding Acknowl- 
edge packet. The receiver would respond 
to the correct packet with an Acknowledge; 
a timeout or an out-of-sequence packet 
would prompt a Negative Acknowledge re- 
questing the correct packet. 

If you are familiar with XModem, Ker- 
mit’s original transfer strategy is similar, 
but with one important difference. Every 
response from the receiver specifies the 
particular packet being acknowledged or 
requested. This feature, lacking in XMo- 
dem, allowed Kermit to easily add sup- 
port for full-duplex packet reassembly. 


Kermit’s Packet-Reassembly Strategy 

Modern Kermit retains the original strat- 
egy for everything except the actual data 
transfer. The initial handshake, start-of- 
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(continued from page 30) 

file, and end-of-file negotiations would 
be more complex if the sender were al- 
lowed to send multiple packets. While 
transferring file data, however, Kermit al- 
lows the sender to send multiple packets 
before receiving an acknowledgment. The 
range of packets that a Kermit sender or 
receiver is still actively managing is called 
the “window.” 

Like most protocols, Kermit limits the 
size of the window. The window size is 
negotiated by the sender and receiver at 
the beginning of the transfer. If the nego- 
tiated window size is 1, the sender will 
wait after each packet for a response. This 
is completely compatible with the origi- 
nal protocol. If the negotiated window size 
is 20, then the sender can send a string of 
20 packets before requiring an acknowl- 
edgment for the first one. 

The window size is not a limit on the 
number of packets that have not been ac- 
knowledged. If the window size is 20, the 
sender cannot send packet number 207 
until it receives an acknowledgment for 
packet number 187, even if every inter- 
vening packet has been acknowledged. 
In addition, the window size cannot ex- 
ceed 32 packets. Both of these restrictions 
are necessary to avoid ambiguity. When 
the receiver sees a packet from the sender, 
it must determine the full packet sequence 
number from the six bits stored in the 
packet header. The only additional infor- 
mation the receiver has for determining 
the full packet-sequence number is the 
window size; the full packet number of 
the packet just received cannot differ from 
the packet expected by the receiver by 
more than the window size. 


Mark 1 
Length 1 
Sequence 1 
Type 1 
Ext. Length 2-3 
HChk 1 
Data 
Check 1-3 


Packet type. 





Window Management 

In my Kermit implementation, the details 
of packet reassembly are handled by the 
“reliability” layer. Lower layers handle the 
transmission and reception of single pack- 
ets. Higher layers handle the transfer of 
entire files. The reliability layer ensures 
that each packet arrives at its destination, 
this is where errors are handled. 

For simpler protocols such as XModem 
and YModem, the receiver’s reliability 
functions wait for the correct packet, send- 
ing negative acknowledgments until the 
expected packet is successfully received. 
The sender’s reliability layer repeatedly 
sends a packet until it is acknowledged. 

For Kermit, this simple picture isn’t suf- 
ficient. To the higher layers, the reliabili- 
ty layer looks the same as the simple case 
previously described. The reliability layer 
functions are still called once to send or 
receive each packet. Internally, however, 
there are significant differences. The reli- 
ability layer must cache data so it can jug- 
gle out-of-order packets. 

Under good conditions, the sender’s re- 
liability function can always return imme- 
diately. Every time the function is called, 
it has already received an acknowledg- 
ment for the first packet in the window, 
so the function can return as soon as it 
sends the new packet, stores the packet 
in the cache, and processes any pending 
packets. 

Under less ideal conditions, the sender 
must exercise some care to keep the trans- 
fer moving smoothly. For example, con- 
sider the situation in Figure 3. Each D is 
a Data packet sent; the Ys are the corre- 
sponding Acknowledge packets. As you 
can see, packet 32 was just sent; the most 


Ext. Len Bytes 


Start-of-packet character, usually Control-A. 
0 or 1, offset by 32, to indicate the extended packet format. 
Packet sequence number, modulo 64, offset by 32. 


Length of data and error check, base 95, each digit offset by 32. 
Error check of previous four fields. 

variable Packet data, prefix encoded. 

Error check of data. 


Figure 2: Kermit long and extra-long packet format. 





Figure 3: Window blocked (window size of 20). 
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CIRCLE NO. 235 ON READER SERVICE CARD 





recent Acknowledge was for packet 25. 
However, no Acknowledge has been re- 
ceived for packet 13. If the window size 
is 20, then no further packets can be sent 
until the acknowledgment for packet 13 
is received, the window is said to be 


“blocked.” In my implementation, the 
sender’s reliability function will not return 
until the window becomes unblocked. 
The challenge for the sender is to keep 
the window from blocking. It can do this 
by correctly determining when to resend 


/* Step 1: Unlink this packet from doubly-linked list */ 


slot 
prev 
next 


sequence number of this packet 
exchange[slot] .previousPacket; 
exchange[slot] .nextPacket; 


if (slot == lastPacket) lastPacket=prev; 
if (prev >= @) exchange[prev] .nextPacket = next; 


if (next >= 0) exchange[next].previousPacket = prev; 
/* Step 2: Link at end of list */ 
exchange[slot] .previousPacket = lastPacket; 


exchange[slot] .nextPacket 


=1: 


exchange [lastPacket] .nextPacket = slot; 





Example 1: Maintaining the list of sent packets. 
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a packet. In Figure 3, if the sender had 
resent packet 13 earlier, it might have re- 
ceived an acknowledgment by now and 
avoided having the window block. 

Just keeping the window from block- 
ing isn’t enough, however. One naive strat- 
egy is to resend a packet whenever a lat- 
er packet is acknowledged. With that 
strategy, the sender would have sent a to- 
tal of 13 copies of packet 13 by the time 
the situation in Figure 3 arose, and would 
likely have received a response from one 
of those repeated packets in time to avoid 
having the window block. But that ap- 
proach would slow the rest of the trans- 
fer; time spent needlessly repeating pack- 
et 13 could have been spent sending 
additional data. The trick is to repeat pack- 
ets soon enough that a response can be 
obtained before the window blocks, but 
infrequently enough to avoid needless du- 
plication. 


Keeping the Books 

As you might expect, the way to break 
this apparent impasse is to track the cor- 
rect data about each packet. There are 
two basic sources of information: se- 
quence and time. 

Unlike some networking protocols, Ker- 
mit operates over serial connections in 
which packet order is preserved. If you 
get an acknowledgment for packet 14 
without seeing one for packet 13, then 
you can reasonably assume that packet 
13 should be repeated; see Figure 4. 

Using packet sequence to detect lost 
packets does not mean using the packet- 
sequence numbers. In Figure 4, packets 
21 and 22 were just sent; the next pack- 
ets sent will be 13 and 23. If at some point 
you receive an acknowledgment for pack- 
et 13, you can use that to check if pack- 
ets 21 or 22 should be repeated. You can 
track the actual packet sequence by stor- 
ing, for each packet sent, the number of 
the previously sent packet. That way, each 
time you receive an acknowledgment, you 
can chain back to check the previously 
sent packets. 

This chaining must be handled carefully 
to avoid degenerate situations. For exam- 
ple, if a packet is sent twice in a row, you 
don’t want it to indicate itself as the pre- 
viously sent packet. I maintain this list as 
a doubly linked list and remove each sent 
packet from the list and reinsert it at the 
end. Example 1 is an outline of the code 
that’s executed every time a packet is sent. 

Of course, even with this sequencing 
heuristic, the window will sometimes 
block. For example, at the end of the file- 
data transfer, the window size is reduced 
to one, which will almost always result in 
a blocked window as the final packets of 
file data are handled. 
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(continued from page 34) 

As before, a blocked window is no 
reason to needlessly repeat the first pack- 
et in the window. Instead, repeat a pack- 
et only when you're reasonably certain 
that enough time has elapsed for a re- 
sponse to have been received. Most pro- 
tocol implementations rely on fixed or 
user-specified timeouts. My Kermit im- 
plementation instead measures the round- 
trip delay and adjusts the timeout based 
on the observed behavior. This only re- 
quires timestamping each sent packet and 


Under poor 
conditions, Kermit is 
faster than ZModem 





measuring the delay when an acknowl- 
edgment is received. To avoid ambigui- 
ty, I only use round-trip measurements 
for packets that were sent once. 

Knowing the average round-trip delay 
isn’t quite sufficient. Some connections 
have a wide variation in the delay. One 
packet might require only four seconds 
for a round-trip; the next might require 
ten. This kind of variation is common on 
some packet-switched networks and when 
transferring files with heavily loaded hosts. 
Again, rather than hard-wiring assump- 
tions about the connection, I measure the 
standard deviation of the round-trip de- 
lay. Example 2 is the method I use for 
tracking the average round-trip time and 
the standard deviation. To avoid overflow, 
I use the definition of standard deviation 
(root-mean-square of the differences from 
the mean) rather than one of the many 
standard formulas. My time routines re- 
turn time values in milliseconds and the 
standard formulas require keeping the sum 
of the squares of the delays. These squares 
will be quite large, and overflowing a 32- 
bit integer is a real possibility. By keep- 
ing a decaying average of the squares of 
the differences, I can more easily bound 
the intermediate values in my standard- 
deviation computation. To compute the 
square root, I use one iteration of New- 
ton’s method on each iteration. From these 
Statistics, I use a timeout interval of the 
round-trip time plus three times the stan- 
dard deviation plus two seconds. 


Implementation 

Listing One (beginning on page 91) pre- 
sents KSendPacketkeliable, the primary re- 
liability function from my implementation 
of Kermit. This function is called with a 
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(continued from page 30) 

packet of data to be sent. It tracks infor- 
mation about the currently outstanding 
packets and processes responses from the 
receiver. The KERMIT_PRIVATE structure 
maintains information about the transfer: 
a pointer to it is passed to each function. 





1 il 2 


Tx: DDDDDDDDDDDDDDDDDDDD 
Rx: SEVEN eee egy 


In particular, the KERMIT_PRIVATE struc- 
ture maintains a cache of 64 EXCHANGE 
structures, one for each possible packet- 
sequence number. Each EXCHANGE struc- 
ture maintains information about a par- 
ticular packet exchange, including the type 
of the packets sent and received, the time 


a a 


Figure 4: Acknowledgement for Packet 13 lost. 


thisDelay = now - <time packet was sent>; 


if (roundTripSamplest+ == @) { 


/* Handle first sample differently */ 


roundTripDelay = thisDelay; 
roundTripDelayDifference = Q; 
Jelse{ 


/* Use real average for first 30 samples, then decaying average */ 


if (roundTripSamples > 3@) 
roundTripSamples=30; 


/* Compute the square of the difference */ 
differenceSquared = (thisDelay-roundTripDelay) *(thisDelay-roundTripDelay) ; 


/* Update the average */ 


roundTripDelay += (thisDelay-roundTripDelay) /roundTripSamples; 


/* Update the mean square */ 


roundTripDelayVariance += (differenceSquared-roundTripDelayVariance) 


/roundTripSamples; 


/* Update root-mean-square using Newton's method */ 
roundTripDelaySD = (roundTripDelaySD + 
roundTripDelayVariance/roundTripDelaySD) / 2; 





Example 2: Estimating the average and standard deviation. 
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the packet was sent, the number of times 
the packet was sent, and pointers to the 
actual packet data. 

The full implementation for my pro- 
gram, which provides basic Kermit file- 
transfer support, is available electronically 
(see “Availability,” page 3). The UNIX ver- 
sion has been compiled using GCC 2.6 on 
FreeBSD 2.0. The serial routines in ftseri- 
al.c may require tweaking for other UNIX- 
like platforms. 


Conclusion 

My earlier Kermit implementations used a 
variety of different heuristics for deciding 
when to repeat packets. One simply re- 
sent the first packet when the window 
blocked; another resent it when certain 
later acknowledgments were received. Re- 
placing those approaches with the heuris- 
tics described in this article substantially 
improved performance and answered 
questions that had arisen from the earlier 
attempts. (For example, it was clear ear- 
ly on that retransmission should be con- 
sidered when the window is blocked and 
when an Acknowledge is received. The 
two different heuristics described in this 
article neatly answered the requirements 
of those two different situations.) 

I’ve timed file transfers with two Ker- 
mit implementations and two ZModem 
implementations over a local modem con- 
nection that lacks proper flow control. In 
this situation, my Kermit implementation 
achieved more than twice the transfer 
speed of any of the three alternatives, and 
was nearly five times as fast as one of the 
ZModem implementations. Although in- 
conclusive, these results suggest that these 
heuristics can allow even imperfect con- 
nections to achieve good throughput. 


Acknowledgment 
Tom Lippincott originally suggested the se- 
quencing heuristic described in this article. 


References 
Frank da Cruz’s Kermit: A File Transfer 
Protocol (Digital Press, 1987) is the defini- 
tive reference on the Kermit protocol. Also 
see http://www.columbia.edu/kermit. 
The source code described here is more 
fully explained in my book The Working 
Programmer's Guide to Serial Protocols 
(Coriolis Books, 1995), which also gives 
in-depth explanations of ZModem and 
Kermit. The sequencing and timeout heur- 
istics presented here are new, however. 
The complete source code from the 
book is available from ftp.coriolis.com in 
the /pub/bookdisk/serial directory. It’s pe- 
riodically updated with bug fixes and oth- 
er improvements. 


DDJ 
(Listing begins on page 91.) 


Dr. Dobb’s Journal, February 1996 


©1991 CompuMentor 


some peop 
put the homeless out 
of their minds. 


Christine Vigil put 


them on-line. 





In 1906 St. Vincent de Paul was 
founded to help people left homeless by the 
San Francisco Earthquake. Today, they're 
an organization that helps thousands of 
homeless people nationwide. By finding them 
shelter, medical care, rehabilitation, and jobs. 

That’s where Christine came in. 
Before she got involved, St. Vincent de 
Paul worked with 75 other San Francisco 
social service agencies matching homeless 
people with available jobs. The Job Finders 
Alliance worked hard, but since they only 
communicated by memo and phone, it 
could take up to three weeks to match a 
qualified person with an open job. 

By using her computer skills, 
Christine was able to put St. Vincent's 
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CGI and the 
World Wide Web 





Debugging CGI 
gateways 





G. Dinesh Dutt 


7 uch of the usefulness of the World 
Wide Web stems from the ability 
of Web servers to interact with ex- 

/ © |) ternal programs. The technology 
that currently makes this possible is the 
Common Gateway Interface (CGD. A com- 
mon application of CGI, for instance, 
might involve a user querying a database 
via a form. Once the form is filled out, a 
CGI script (or program) passes the request 
from the Web server to the external 
database, gets the database output, and 
sends it back to the user. 

More specifically, CGI identifies how 
the Web server should supply input to the 
external programs, along with the format 
of output to be returned. The server, in 
turn, gets inputs from a client such as a 
Web browser. Since inputs are normally 
made available via the clients, I’ll assume 
for this article that the interaction occurs 
between the client and the gateway (ex- 
ternal programs), instead of between the 
server and gateway. Currently, HTTP 
servers are the only Web servers that sup- 
port CGI. This means that CGI is sup- 
ported on all familiar platforms— UNIX, 
Macintosh, and Windows. 





Dinesh is an engineer with Hinditron- 
Tektronix Instruments Limited, Bombay, 
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The basic tools you need to use CGI are 
a language that produces executables (shell 
scripts, Tcl, Perl, or C, for instance) and 
access to a CGJ]-enabled HTTP server. This 
article is based on UNIX, Perl 4.036, the 
NCSA HTTPD 1.4 and CERN HTTPD 3pre6 
servers, and CGI 1.1, but it applies to oth- 
er servers, languages, and platforms. For 
the sake of example, I’ll build a simple 


form-based application (for information 
on forms, see “Coding with HTML Forms,” 
by Andrew Davison, Dr. Dobb’s Journal, 
June 1995) that uses the form in Figure 1. 
Listing One (listings begin on page 92) pre- 
sents the HTML code that generates this 
form. As you can see, this form consists 
of a text box and two radio buttons, only 
one of which can be selected. This pro- 
vides a gateway with Author and Title in- 
puts. Input is passed to the gateway when 
the user clicks the Submit button. 


Data Input 

There are several ways in which input is 
passed to gateways, including forms-based 
methods and ISINDEX. While each method 





supplies inputs differently, they all use en- 
vironment variables to pass information. 
The environment variables in Perl are avail- 
able via the %ENV associative array. RE- 
QUEST_METHOD is one such variable 
that indicates the method used to submit 
the input. (See Table 1 for a description 
of additional environmental variables CGI 
uses.) 

In Example 1(a), the form has an AC- 
TION METHOD set to GET, so the input 
is available to the gateway in the environ- 
ment variable QUERY_STRING. With forms 
where the ACTION METHOD is set to 
POST, input is available via stdin (standard 
input). The CGI specification states that the 
server need not supply an end-of-file (EOF) 
for the input available via stdin. Instead, 
the HTTP server provides the size of the 
input in the environment variable CON- 
TENT_LENGTH. The first gotcha comes 
here, when gateways try to read this input. 
Since the input is not terminated with an 
EOF marker, the gateway must never read 
more than the CONTENT_LENGTH or it 
will wait for further input that will never 
come. This hangs the gateway and the client 
awaiting the results. Example 1(b) reads 
stdin to secure the input. 

When input is supplied via the ISIN- 
DEX interface, the input is made available 
via the command-line arguments array 
ARGV. You can use standard command- 
line-argument parsing code to extract the 
inputs. The REQUEST_METHOD variable 
is set to GET in this case, too. Informa- 
tion supplied via ISINDEX is sent as part 
of the link, separated by a “?”; for exam- 
ple, bttp://amadeus.org/playZupiter, where 
Jupiter is made available via command- 
line arguments (S$ARGVI[OJ, in this case). 
But remember, the arguments cannot have 
blank spaces between them— even if you 
“quote” the spaces. To pass arguments 
with spaces in them, replace each space 
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(continued from page 42) 

with its equivalent hexadecimal ASCII 
code prefixed by %; for example, bttp:// 
amaddeus.org/play?41st%20Symphony will 
make the gateway receive “41st Sympho- 
ny” as its first argument. 


Making Sense of the Input 

If you were to simply print out the input, 
the result would be gibberish. One way 
to see what the gateway receives is to use 
the test-cgi program that’s supplied with 
the NCSA HTTPD. For example, to ex- 
amine what QUERY_STRING (which is 
using the GET submission method) looks 
like to the gateway, you can set the AC- 
TION to be “test-cgi’(prefixed by the 
proper http://your-server:port/cgi-bin/) in 








Figure 2: Forms-based interface of the debugcgi program. 


et 


the example form name=ThetFountain- 
head& keyword=title. 

The inputs are presented to the server 
as a list of name=value pairs, with each 
pair separated by a “&” character. This 
format also converts blank spaces to “+” 
and converts all special characters to their 
hexadecimal ASCII code. There are stan- 
dard libraries available in many languages 
to decode the input and present it in an 
understandable format. Listing Two pre- 
sents CGIGetInput, one such decoder writ- 
ten in Perl. 

CGIGetInput understands both GET and 
POST methods and returns the inputs in 
an associative array (name supplied by the 
caller), with each input-field name being 
the key and the value of the field being 
the value of the array 
element. You can use 
the decoded output 
for processing. For 
instance, the debug- 
cgi.cgi script of List- 
ing Three uses this 
routine. 

However, in case 
of ISINDEX, the data 
format is different 
from the aforemen- 
tioned cases. The 
name part is entirely 
absent and the data 
is as submitted by the 
user with all hex- 
adecimal symbols 
converted to their 
ASCII equivalents. 
For instance, in the 
aforementioned ex- 


(a) 


] 
(b) 


exit; 


, 
} 


&PrintHeader; 


&PrintHeader 


if (SENV(' REQUEST. METHOD'} eq 
if (!defined “(SENV(' CONTENT. _LENGTH'))) { 
print "Error: CONTENT_LENGTH not set\n"; 








ample, the gateway gets “41st Symphony” 
even though we said “41st%20Symphony.” 


Talking Back 

When the gateway needs to communicate 
with the server after processing, it can re- 
turn the type of the forthcoming output 
via the Content-type header. For an HTML 
document, this would be “Content-type: 
text/html.” If you do not specify the type 
of the data returned, the browser returns 

“500 Server Error” message to the user. 
The error logs of the server contain the 
reason “malformed header from script.” 
This happens because HTTP first sends 
some metainformation about the object 
that it’s about to return— type, size, title, 
expiration date, and so on. If this infor- 
mation isn’t forthcoming, the server is un- 
able to parse the input and returns the 
aforementioned error message. The valid 
types that can be used in place of 
text/html are those that are supported by 
the browser/HTTP server. This is given 
by the HTTP_ACCEPT environment vari- 
able. (Remember, not all browsers sup- 
port all environment variables.) For plain 
ASCII texts, text/html can be replaced by 
text/plain. 

Another effect of the processing could 
be a request to fetch another document. 
To do this, the URL of the document is re- 
turned in the format print "Location: 
http://amadeus.org/Mozarnts_Life.html\n\n". 
which tells the server that it must retrieve 
the supplied URL and return that to the 
client. You could also use the PrintHead- 
er routine supplied in cgi-parse; see List- 
ing Two. Example 2 provides typical call- 
ing sequences. 


if (SENV({'REQUEST_METHOD'} eq "GET") { 
_ Sinput 


= $ENV('QUERY_STRING'}; 


"DOST" ) { 


read (STDIN, $buffer, $ENV{'CONTENT_LENGTH}) ; 


Example 1: (a) Accessing the contents of QUERY_STRING; 
(b) reading input via stdin. 


# Using the cgi-parse.pl, 


Print just the default 
text/html; 


&PrintHeader ("text/plain") # Print type to be 


text/plain. 


# Redirect request to get new document 


("http: ://amadeus. org/Mozarts_ Life. html", 1); 


Example 2: Typical calling sequences. 
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(continued from page 44) 
Yet Another Input Method 
Another method for obtaining input in- 
formation makes use of the PATH_INFO 
environment variable. To illustrate, assume 


HTTP_REFERER 


that you have a document that is avail- 
able in both French and English. De- 
pending on the user’s choice of language, 
the correct document-must be served. If 
you have a CGI script called “document- 


Contains the exact URL in which the script was 


invoked; for example, http://www.halcyon.com/ 
htbin/browser-survey. In some older versions of 
browsers, this is called as REFERER_URL. 


HTTP_USER_AGENT 


Gives the name of the browser through which 
the script was invoked. Using this, one could 
serve different browsers different documents, 


one with or without netscapisms. 


REMOTE_USER 


If authentication is enabled, this returns the 


name for which the authentication succeeded, 
the server must support it. 


REMOTE_ADDR/REMOTE_HOST 


Remote machine making the request. If the 


hostname is unavailable, only the address is set. 


SERVER_PROTOCOL 


States the protocol and the version of the 


protocol being used. Currently HTTP 1.0 and 
HTTP 0.9 for older servers. 


GATEWAY_INTERFACE 


Name of the gateway interface being used and 


the version number (currently CGI 1.1). 


AUTH_TYPE 


Protocol-specific authentication supported by the 


server. Currently, the only valid value is “Basic? 


SERVER_SOFTWARE 


Name of the server: NCSA 1.4, for example, for 


the NCSA server version 1.4. 





Table 1; Environment variables used by CGI. 
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disher,” for instance, a link could be spec- 
ified as: 


http://mymachine.org/cgi-bin/document- 
disher/French/Mon_Document 
http://mymachine.org/cgi-bin/document- 
disher/English/My_Document 


In this case, the CGI script could make 
use of the extra path information avail- 
able at the end of the pathname to retrieve 
the correct lingual document. 

The server also provides an environment 
variable PATH TRANSLATED, which con- 
tains a complete, legal filename based on 
PATH_INFO. Consequently, this “multi- 
lingual” document gateway could simply 
print the contents of the file specified in 
PATH_TRANSLATED if the paths are con- 
figured properly. 


Which Input Method? 
The input method you use depends on 
your application. GET can be used when 
there’s little information to be supplied; 
for instance, a form like Figure 1, that sup- 
plies only a keyword and the type of the 
keyword. If your form involves more data, 
the contents of the environment variables 
may be truncated. Consequently, you 
should use the POST method for large in- 
puts. (The Mosaic forms tutorial recom- 
mends use of the POST method only.) The 
ISINDEX approach to input, on the other 
hand, lends itself to querying and works 
well when you don’t know if forms are 
being used or when you have to support 
browsers that don’t support forms. 

Also, keep in mind that you can mix dif- 
ferent input methods to some extent: 


http://mymachine.org/cgi-bin/document- 
disher/French/Mon_Document?Speak 
http://mymachine.org/cgi-bin/getfc?7791+793 


When forms are used as the method to 
submit input, people might want to pass in- 
formation not modifiable by the user (the 
form name, for example). You can do this 
by adding a ? followed by the form name 
to the URL of the action link (or via 
PATH_INFO). While it’s okay to do so, your 
script must “know” that the input would be 
available in two different ways and read 
both of them; for example, by manually 
changing the REQUEST_METHOD variable 
from within the script. However, the correct 
way to pass information that’s not modifi- 
able by the user (again, the name of the 
form) when using forms is via hidden fields, 
specified via the TYPE="hbidden" attribute in 
the form field. 


Debugging Gateways 

A gateway is like any other program in 
that you will need to be able to debug it. 
One of the basic problems with CGI is 
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(continued from page 40) 

that the scripts seem to work when used 
normally, but fail when called from with- 
in a Web browser. The lack of error mes- 
sages makes this doubly confusing. 

One way to debug gateways is to sim- 
ulate the behavior of the HTTP server by 
setting all the relevant environment vari- 
ables (QUERY_STRING with the METHOD 
set to GET, for instance) and executing 
the script to see if the decoding of infor- 
mation is correct. However, this does not 
test the changed environment under which 
the gateway works once it’s invoked by 
the WWW server. 

Consequently, I’ve written a program 
that reports errors in your gateway’s exe- 
cution, including those caused by wrong 
assumptions about the environment. Us- 
ing this program (which has its own forms- 
based interface; see Figure 2), it should 
be fairly easy for you to debug your gate- 
ways, and the gateway need not even be 
written in Perl. 

The test script/form as shown in List- 
ing Four works as follows: 


1. Replace the action URL in the debug 
form (see Listing Five) with the correct 
path to debugcgi.cgi in your machine. 
Ensure that the cgi-parse.pl file is put 
in the @INC of the debugcgi.cgi script 
and is made world readable. The de- 
bugcgi.cgi script needs to be world 
readable and executable. 

2. Change the paths to the actual location 
for Perl (replace /usr/local/bin/perl). 
3. If you use forms to supply input, strip 
off the <FORM> and </FORM> lines from 
your form and attach the resulting body 
of the form to the debug form provided. 
For ISINDEX interfaces, supply the ar- 
guments in the ISINDEX area of the form. 

4. Bring up a browser on this form. 

5. Enter the full pathname of the script in- 
voked by the form to test and also sup- 
ply the METHOD used to submit in- 
formation. 

6. Supply the input to your form. 

7. Click on Submit. 


If everything is okay with your form, 
you are notified accordingly, and the out- 
put from the form is displayed. (The pro- 
gram currently lacks support to handle 
pure image outputs.) If not, an error mes- 
sage is displayed and the cause of the er- 
ror reported, including any parsing errors 
for a script. All errors resulting from a 


change in the environment (user to the 
server) are trapped and reported. Let’s take 
a look at some of the common errors en- 
countered in writing gateways. 

One of the more common errors is to 
not provide all of the required environ- 
ment to the script. When testing, the script 
is running with its user id set to your id, 
so it has access to your entire environ- 
ment, files, and databases. However, when 
running under the server’s control, it runs 
with the user id set to that of the server, 
usually “nobody,” so it doesn’t inherit your 
environment. Thus, executables accessi- 
ble during testing might not be found in 
actual use. Similarly, files readable during 
testing might suddenly become unread- 
able. The necessary files should be world 
readable and world executable, and if they 
need to be written to, world writable. 

Another common error occurs when 
you do not send the Content-type line as 
the first line of the output returned by 
CGI. Make sure the first two lines of the 
form are the Content-type line followed 
by a blank line; otherwise, the “malformed 
header” error appears. The Content-type 
field needs to be set to the type of the ob- 
ject being returned. 

Also, by printing a Content-type line at 
the very beginning or before printing an 
error message, you can redirect the errors 
to the user; otherwise, error messages end 
up in the daemon’s error log. 

You should also ensure that your HTTP 
server supports CGI Version 1.1 and that 
the server is running with the ability to rec- 
ognize and execute CGI scripts. Many sites 
turn off CGI since it can be a security hole 
if not properly configured. In the case of 
NCSA HTTPD, the directive ScriptAlias 
gives the paths that can contain scripts. 
Also, if the Add7Type directive is defined as 
Add Type application/x-httpd-cgi.cgi, then 
a script ending in .cgi can be recognized 
anywhere the server has access. Both di- 
rectives are to be present in the srm.conf 
file. For the CERN server, scripts are con- 
figured via the Exec directive. 

The script must be placed in the prop- 
er directory, and the server must be ca- 
pable of recognizing a file with a specif- 
ic suffix, such as “.cgi,” as a script to be 
executed. 

A simple problem with the CERN serv- 
er is caused by its parsing policy. If the 
path to your script is passed/rejected be- 
fore it encounters the desired Exec rule, 
the script will not be executed, but its con- 







dine 14. 


panic: realloc at /usr/local/bin/rfc2html line 93, <RFC> line 1003. 

Can't open 1057: No such file or directory 

/usr/local/bin/rfc2html did not return a true value at 
/usr/local/etc/httpd/cgi-bin/rfc2html line 52, <> 


[Mon May 22 69:59:15 1995] httpd: malformed header from script 


Figure 3: Error messages for server’s error_log. 
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(continued from page 48) 
tents are returned as a document (in case 
of a reject, an error message is returned, 
not the script as a document). To prevent 
this, ensure that the Exec rules come first 
for those directories containing scripts. 
When troubleshooting, view the error 
log file for the HTTPD server you're using. 
The location of this file is difficult to pre- 
dict; it varies from a standard/var/htt- 
pd/logs/error_log to /ustr/Ical/dolphin/htt- 
pd/logs/error_log. Figure 3 shows the 
contents of my server’s error_log when 
problems occurred. One problem immedi- 
ately apparent from this log is that some of 
the errors do not indicate which script was 
the cause of the error message. The “Can't 
open 1057” error is one such example. 
These errors are normally system related, 
such as a call to an external program via 
system(). To properly trap and report sys- 
tem errors, include the name of the script. 
It might make sense to print the contents 
of the environment variable HTTP_REFER- 
ER (Gif available), which contains the the 
URL specified to get to this script. 
Furthermore, when using forms with the 
POST method, you must not expect an 


HTTP/1.0 200 OK 


Content-type: text/plain 
Server: NCSA/1.3 





Figure 4: Headers returned by the 
nph -test-cgi script. 


NCSA’s documentation on CGI 


http://noohoo.ncsa.uiuc.edu/cgi/intro.htm| 


CGI specification 


EOF; instead you must access the CON- 
TENT_LENGTH environment variable to 
get the number of bytes to read and then 
read only that much. Otherwise, your script 
will hang. One nice feature of CERN 
HTTPD Version 3 is the ability to specify a 
timeout period. If the script doesn’t termi- 
nate within that time frame, it’s killed. This 
is specified via the ScriptTimeOut directive, 
and has a default value of five minutes. 

If you're mixing output from your script 
with output from external programs called 
from within the script, you should un- 
buffer the output or else the output could 
be in some nonpredictable order. Also, 
unbuffering STDOUT seems to improve 
performance, as the server gets output 
from the gateway immediately instead of 
waiting until the buffer is full. 


Sending Output to the Browser 

In every case, the gateway spews out data 
without having to bother with HTTP reply- 
header format and conventions. The serv- 
er looks at this output and adds headers 
conforming with the HTTP protocol be- 
fore sending it to the client. If you wish 
to save the overhead of your server pars- 
ing the output, you may do so by 
prepending the appropriate HTTP re- 
sponse headers. 

To prevent the server from parsing the 
output of such scripts, the scripts should 
have names that begin with “nph-”. For 
example, NCSA HTTPD comes with a 


http://noohoo.ncsa.uiuc.edu/cgi/interface.html 


The HTTP draft 


http://info.w3. SEO Ne html 


CGI FAQ 


http://Awww.halcyon.com/hedlund/cgi-faq/ 


Yahoo index for CGI material 


http://akebono.stanford.edu/yahoo/Computers/World__ Wide _Web/CGI 


_Gateway_Interface/ 
Virtual library material on CGI 


__COMmmon | 


http://www.charm.net/~web/Vlib/Providers/CGI.html 


CGl-related newsgroups 
news://comp.infosystems.www.authoring.cgi 


Currently available gateways 


http://www.ws:.org/hypertext/WWW/Tools/Filters.html 


http://www.nr.no/demo/gateways.html 


http:/www.halcyon.com/hedlund/cgi-faq/gateways.html 
http://www.cis.ohio-state.edu:80/hypertext/about_this_cobweb.html 
Language libraries for decoding forms input and other useful things 
http://wsk.eit.com/wsk/dist/doc/libcgi/libegi.html - C 
http://www.bio.cam.ac.uk/web/form.html - Perl 
http://www.I|bl.gov/~clarsen/projects/htcl/http-proc-args.html - Tcl 

Survey of which browsers support which variables 
http:/www.halcyon.com/htbin/browser-survey 





Table 2: Web sites for information on CGI. 
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script called “test-cgi.” The same script 
that talks directly to the browser is named 
“nph-test- cgi.” 

The main difference between such scripts 
and ordinary scripts is in the extra two lines 
that are prepended to the output. The first 
is the status-code line and the second is 
the server: line that specifies the server 
name and version. You need to look at the 
draft on HTTP to know all the valid status 
codes. For example, the nph-test-cgi script 
returns the headers in Figure 4. 


Customized Responses to Problems 
The NCSA HTTPD 1.4 server lets you cus- 
tomize the error message returned. For 
example, you could customize the re- 
turned error message for a “500 Server Er- 
ror” by calling a script that would present 
a more informative message. To do this, 
examine the srm.conf file which contains 
these lines at the end: 


ErrorDocument 302 /cgi-bin/redirect.cgi 
ErrorDocument 403 /errors/forbidden.html 


This means that the redirect.cgi script 
will be invoked when a redirect error 
occurs. 


Security 
Security is a crucial issue when writing 
CGI scripts because you are in effect al- 
lowing other users to execute programs 
on your machine based on their inputs. 
Many of the problems encountered in writ- 
ing CGI scripts in this respect are similar 
to those encountered when writing UNIX 
setuid scripts. Consequently, you should 
always follow the simple rule: Do not trust 
the client input at all. For example, do not 
blindly use the client input to construct 
commands for the system to execute or 
supply as input to eval. Do not even print 
the value input to your script (except dur- 
ing testing, of course) as hackers can use 
clever sequences to break into the system. 
Further security is possible via the au- 
thentication mechanisms provided by most 
servers, which require the user to key in 
a username and password. Only if this val- 
idates is the user allowed to execute the 
script. Details on how to configure the 
server to do this are beyond the scope of 
this article. Refer to your server manuals 
for details. 


Conclusion 

The net is a rich source of CGI informa- 
tion and numerous, freely available pro- 
grams to ease your job of writing and de- 
bugging gateway applications. Refer to the 
list of web sites in Table 2 for more in- 
formation on CGI. 


DDJ 
(Listings begin on page 92.) 
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Using Server-Side 





Includes 





A simple but powerful 
technique 





Matt Kruse 


the World Wide Web, you’ve probably 
seen pages that contain information or 
images generated on the fly that change 
each time you load the page. Whether it’s 
a counter to tell you that you’re visitor 
#1000, a greeting that says “Welcome, vis- 
itor from yoursite.com,” or an up-to-the- 
minute schedule for a tourist attraction, it 
can be created using server-side includes. 

Server-side includes (SSIs) are simply 
commands embedded inside regular 
HTML documents that make your page do 
something different each time it is load- 
ed. By using SSIs, you can create dynamic 
pages that will make your site stand out 
from the WWW pack. In this article, I’ll 
describe the format of these commands, 
show how they work, and discuss how 
you can write programs to work with your 
Web pages. 


The WWW Server 

Most WWW servers have a fairly simple 
job: When a request for a page comes in, 
they load the correct file from disk and 
send it out to the right place. If you put 
SSI commands inside your HTML docu- 
ment, however, things must happen a lit- 
tle differently. First, you need to tell the 
server to parse the document for embed- 
ded SSI commands, which are to be exe- 
cuted before the document is sent. By 





Pity 


Matt is a computer-science student and a 
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f you've done any browsing at all on’ 


default, most servers will not parse doc- 
uments at all, so any SSIs will simply be 
ignored. If you haven’t put any commands 
inside your documents, there’s no reason 
for the server to search every single file 
before sending it to the client. Likewise, 
if you use SSIs in only a few pages, the 
server needn't parse those pages that don’t 
have them. So, most servers have a way 
to distinguish which pages should be 
parsed and which should not. 





Usually, the server decides what to 
parse based on the filename. If the file 
ends in .html, it is delivered unparsed; if 
it ends in .shtml, it is searched for SSI com- 
mands. Of course, you can change this 
convention. For those servers that can han- 
dle the extra load of parsing all documents, 
you may wish to enable SSI parsing for 
all .html files. 

Some servers (the CERN server, for in- 
stance) do not yet support SSIs. Also, the 
commands and formats are not a standard 
and may vary from one server to anoth- 
er. The examples I present here work cor- 
rectly with both the NCSA httpd and 
Netscape servers, and should also work 
with other servers, or at least be close 
enough to modify easily. 


SSI Format 

What do SSI commands look like, and 
how does the server handle a command 
once it is found? All SSI commands are 
conveniently placed inside standard HTML 
comments so that the commands will not 
be displayed if a page ever gets to users 
without being parsed. In HTML, any text 
between “<!--” and “-->” is considered a 
comment. Consequently, the general for- 
mat for an SS] command inside an HTML 
document is as in Example 1(a). Several 
different commands are available, each 
taking its own arguments using either one 
or two tags. 

The #exec command executes an ex- 
ternal program and includes its output in 
your document. It takes one of two op- 
tions: cmd, which executes a single com- 
mand using /bin/sh; or cgi, which gives 
a virtual path to a program to be execut- 
ed. For example, to call a program in the 
same directory as the HTML page that the 
command is located in, you would use 
the command in Example 1(b). 


Writing the Program 

Once you understand how commands are 
placed into HTML documents, the next 
step is, of course, to write a program to 
be executed. Your program can be writ- 
ten in any language that is executable on 
the server. This means C, Pascal, awk, 
Fortran, and so on, although the most 
common choice is Perl. Most scripts are 
written in Perl because it is easy to write, 
has great text-manipulation capabilities, 
and doesn’t require lengthy compiles. 
Also, many Perl scripts and libraries are 
available on the Internet for download- 
ing and use. All the examples in this ar- 
ticle are in Perl. 

The interaction between the program 
and the HTML page is simple. Whatever 
information is sent to STDOUT from your 
script is inserted into the page and treat- 
ed just as if it were there to begin with. 
On some servers, anything sent to STDERR 
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(continued from page 52) 
will get appended to the error log, which 
is helpful in debugging. 

Every program used in an SSI must re- 
turn two things: a MIME type identifier 
and any output to be included in the doc- 
ument. As you can see from Example 1(c), 
the first line output by the program is the 
MIME type; this tells the browser how to 
handle the data you'll be sending. In the 
example, this is "Content-type: text/html", 
which says that the information that fol- 
lows is of type fext and subtype html. The 
two newlines at the end of the MIME type 
header are always required. (One of the 
most common mistakes that new pro- 
grammers make is not returning the MIME 
header in the correct format, including the 
empty line, which results in an error.) 

After you’ve told the browser how to 
treat your data, any output from your pro- 
gram will be inserted into the document. 
The server doesn’t check whether you’ve 
returned anything that it isn’t ready to han- 
dle—for example, an image or other bi- 
nary data— so be careful about what you 
send. The third line in Example 1(c) sim- 
ply places the text “Hello, World” into your 
document wherever the SSI call is locat- 
ed. Example 2(a) is the original HTML 
document. Once the server parses the doc- 
ument and executes "script.cgi", the actu- 
al HTML code is sent to the user’s brows- 
er; see Example 2(b). 

If users view the source code for the 
just-received HTML page, they will see 
the processed HTML, not the source that 
contains the SSI command. Users don’t 
even know that a command was execut- 
ed. This example of a script that inserts 
the same text each time the SSI command 








(a) <!--#command tagi="valuei" 
tag2="value2"--> 








(b) 
(c) 


<i--fexec cgi="script.cgi"--> 










#!/usr/bin/perl 
print "Content-type:text/html\n\n"; 
print "Hello, World"; 







Example 1: (a) General format for an 
SST command, (b) an instance of the 
#exec command; (Cc) script.cgi. 


<html> 

<hi>Sample output</h1> 
<p>Here is the script output: 
<!--#exec cgim"script,.cgi"--> 
</p> 

</html> 


<html> 

<hi>Sample output</h1> 

<p>Here is the script output: 
Hello world!</p> 


</html> 





Example 2: (a) HTML document that 
invokes a script via an SSI; (b) resulting 
HIML stream that is sent to the client. 
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is invoked has no practical value. Instead, 
SSIs are usually used to return output that 
changes with each load of the page. A 
better example, one that represents per- 
haps the most-common use for SSIs, is a 
“counter” script. You’ve probably en- 
countered this many times: a Web page 
with a counter that keeps track of how 
many times the page has been loaded and 
displays the current count to each visitor. 

Example 3(a) presents a simple counter 
script that uses a file to store the current 


The access counter 
1S Just one of many 
possible uses for 
server-side includes 


number of accesses to the page. Each time 
the script is run inside an SSI, it reads the 
current count from the file, increments the 
count, writes the new value back to the 
file, and prints the value to STDOUT. The 
script also uses file locking, which is vital 
in a script such as this. Without file lock- 
ing, two people accessing your page at 
the same time would both cause the pro- 
gram to read and write to the file at the 
same time, possibly causing the count to 
be lost. 

After printing out the MIME header in 
line 2 of the script, the file containing the 
counter value is opened with both read 
and write access. The program then gets 
an exclusive lock on the file using flock(), 
reads the first line of the file into the 
$count variable, resets the file pointer to 
the beginning of the file, and increments 
the variable. The program then prints the 
variable twice— once to STDOUT to in- 
sert it into the HTML document, and once 
to the file to store the new value. The ex- 
clusive lock is then given up, the file is 
closed, and the program is finished. 

Example 3(b) includes a counter in an 
HTML file. When the count is returned 
from the script, the count is placed be- 
tween the <B> and </B> tags, making the 
count appear bold in the browser. Using 
this script inside of a WWW document will 
let you keep an ongoing page-access 
counter. 


include file 


echo 
file size 
last modified 


Table 1: Additional SSI commands. 





Improving the Counter 
Although the previous counter script will 
do the job just fine, some improvements 
can make it more flexible. Rather than sim- 
ply keeping track of the count for a sin- 
gle page, it would be nice to modify the 
script to keep track of counts for any page 
that calls it. You could then use a counter 
on any page on a WWYW site by inserting 
the same command and have it automat- 
ically keep separate counts for each page. 
You can accomplish this with only a 
few modifications to the original program. 
One environment variable available to 
scripts running under the NCSA (and some 
other) servers is DOCUMENT_URI, which 
contains the virtual path and filename of 
the HTML page that the script is being 
called from. You can then use this to de- 
tect which page is making the counter re- 
quest and load the appropriate file. 
Example 4 is a modified version of the 
counter script that incorporates these 
changes. First, it replaces all “/” characters 
from the caliing URL with underscores to 
create a valid filename. If the resulting file- 
name exists, it is used as the counter file, 
just as before. If it doesn’t exist, the file is 
created and 0 is inserted as the current 
count. This type of counter script would 
be especially helpful for a commercial 
Web-presence provider who wants an easy 
way for customers to add counters. 


Other SSI Commands 

While the #exec command may be the 
most useful and flexible, other SSI com- 
mands are useful in HTML documents. 
Table 1 presents some additional SSI com- 
mands found in the NCSA server. 


e #include inserts a file specified by the 
virtual tag into the HTML document. This 
is a good way to provide, say, a stan- 
dard footer at the bottom of each of your 
pages. You can then just insert the in- 
clude command in each page, and have 
only one file. If you want to update your 
footer with more information or change 
it in any way, you only have to change 
a single file. You can also use the ‘file’ 
tag if you are referencing a file in the 
same directory as the HTML document. 
#echo inserts the value of any one of 
the environment variables currently avail- 
able from the server. You can use sev- 
eral variables, including the remote 
user’s IP address, information about the 
server, the user’s name if it is available, 
and so on. 


<!--#include virtual="path/to/file"--> 
<!--#echo var="Environment Variable"--> 
<!--#fsize virtual="path/to/file"--> 
<!--#flastmod virtual="path/to/file"--> 
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CIRCLE NO. 101 ON READER SERVICE CARD 

















(a) #!/usr/bin/perl 
print "Content-type: 
text/html\n\n"; 
open(COUNTER,"+< counter.txt"); 
flock (COUNTER, 2) ; 
Scount=<COUNTER> ; 
seek (COUNTER ,@,@) ; 
Scount+t+; 
print "Scount": 
print COUNTER "Scount"; 
flock (COUNTER, 8) ; 
close (COUNTER) ; 


<html> 

<h1>Welcome</h1> 

You are visitor #<b><!--#exec 
cgi="counter.cgi"--></b>. 

<p> 

</html> 





Example 3: (a) A simple counter script; 
(b) HTML page that invokes the counter. 


#!/usr/bin/perl 
print "Content-type: text/html\n\n"; 
($PAGE = SENV{ ' DOCUMENT_URI'}) aa 
Bi/ vers 

unless (-e SPAGE) { 

open(NEW,"> S$PAGE") ; 

print NEW "0"; 

print "0": 

close (NEW) ; 

exit (Q) ; 

} 


open(COUNTER,"+< $PAGE") ; 
flock (COUNTER, 2); 
Scount=<COUNTER> ; 

seek (COUNTER,@,@) ; 
Scount++; 

print "Scount"; 

print COUNTER "Scount"; 
flock (COUNTER, 8) ; 
close(COUNTER) ; 





Example 4: Improved version of the 
counter script. 


(continued from page 54) 

e #fsize prints the size of the file specified 
with the tag. The "file" tag is also valid 
for the command, as with #include. 

e #flastmod displays the last modification 
date of the file given in the tag. The “file” 
tag is also available. 


For details on more commands, refer 
to the documentation for the NCSA serv- 
er or the server you are using. Another 
good place to look is http://hoohoo 
ncsa.uiuc.edu/docs/tutorials/includes.html. 


Conclusion 

This access-counter example is a useful 
script, but it is only one of many possible 
uses for SSIs. For example, SSIs can dis- 
play a random image, present a welcome 
message to a user, update a private log of 
access statistics, output different text de- 
pending on the user’s browser, or auto- 
matically redirect the user to a different 
page. SSIs can make your Web pages 
more dynamic and interesting, and those 
who visit your site will have another rea- 
son to come back. 


DDJ 


Dr. Dobb's Journal, February 1996 





12 issues 
$34.95. 


41% off! 


“Tthas 





Windows’ Q & A 
Matt Pietrek page 81 


Win32° Q&A 
Jeffrey Richter page 87 


C/C++ Q&A 
Paul DiLascia page 93 


VOL 9 NO 10 $4.95(5.95CAN) 


Advanced 3-D Graphics for 
Windows NT 3.5: Introducing 
the OpenGL Interface, Part | 


OpenGL” puts sophisticated 3-D graphics within reach of every 


developer targeting Windows NT” The OpenGL software interface 
makes it relatively easy to create complex objects complete with 


shading, lighting, hidden surface removal, and even texturing. 


Chicago's Interface Gadgets, 
Part Ill: Programming Properly 
With Property Sheets 


The rest of the world calls them tabbed dialogs, but in the Chicago 
SDK and MFC 3.0 they’re known as property sheets. Dave Edson 
completes his trilogy on new Chicago controls by detailing multiple 
ways to create them using C and the Chicago API, or MFC. 


Dave Edson 


Building Windows NT-Based 
Client/Server Applications 
Using Remote Procedure Calls 


RPCs are one of the easiest mechanisms with which to distribute 
computing. The RPC model is fundamentally simple: your client 
application thinks it is calling a local function, when in fact the 
function’s implementation resides in a remote server program. 


© 


James Finnegan 





informatio 











I cant get 
anywhere 
else.’ 








Ce. 


_J Bill me _] Payment enclosed 


Name 





Address 





City/State/Zip 
FOR FASTEST SERVICE USE YOUR CREDIT CARD: 





QYVISA QO Mastercard O American Express 


Account: Expiration: 


Annual newsstand price: $59.40. Foreign subscriptions must be prepaid in U.S. 
dollars drawn on a U.S. bank. Canada and Mexico: $65/year. Canadian GST 
included. All other foreign countries $70/year (airmail). 


Guarantee: If you are ever dissatisfied with Microsoft Systems 
Journal, simply request a full refund on all unmailed issues. Allow 





ae weeks for delivery. ane | 


Clip and send to Circulation Dept., Microsoft Systems Joumal, 
PO Box 56621, Boulder, CO 80322-6621 or fax to (415) 905-2233 








Java Command-Line 








A Java package for 
parsing command-line 
parameters 





Greg White 


| @ sers of the first release of the Web 
| | server my company developed made 
A | |) one request more often than any 

mm other: “Please include printed doc- 
umentation.” In the first release, docu- 
mentation consisted of more than 160 
HTML files, viewable from any browser 
supporting HTML 2.0. While users could 
load documents into a browser and print 
them, all links ended up getting lost— not 
to mention that the printing sequence 
wasn’t clear. For our part, we also need- 
ed a formatted text version of some of the 
documentation for reference as comments 
within configuration files. 

While trying to solve this problem, I ran 
across RtfToHtml, a program that converts 
rich text format (RTF) documents to HTML 
(see ftp://ftp.cray.com/src/WW Wstuff/ 
RTF/rtftohtml_overview. html). Unfortunate- 
ly, our source documentation was already 
in HTML, so we would have had to convert 
it to RTF and manually insert the styles that 
RtfToHtml can handle. Instead, I wrote a 
program that reads in HTML and writes out 
RTF. By the time I was done, I had written 
a system that has, at its core, a Java appli- 
cation that converts an HTML file to an RTF 
file (with links preserved as bookmarks) or 





Greg, a programmer at I/NET, is current- 
ly working on the Web Server/400 prod- 
uct, a commercially available Web server 
for AS/400 computers. He can be contacted 
at gwhite@inetmi.com. 
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text file. The name of the application (and 
its package of classes) is Htm/XIate. 

In this article, I'll introduce CmdInArg, 
a package of Java classes which parses 
the command-line parameters for the ap- 
plication. In future articles, I’ll detail the 
process of converting HTML to RTF and 
formatting text. This article and the ac- 
companying code are based on the 1.0 
beta of the Java development kit DK). 


The Java Programming Language 
Developed by Sun Microsystems, Java is 
an object-oriented language similar to C++. 
The language has garnered attention be- 
cause its portability, security, and support 
for distributed programming make it use- 
ful for Internet programming. To find out 
more about Java, refer to the articles “Java 
and Internet Programming,” by Arthur van 
Hoff (DD/, August 1995), “Net Gets a Java 
Buzz,” by Ray Valdés (Dr. Dobb’s Devel- 
oper Update, August 1995), and “Program- 
ming HotJava Applets,” by John Rodley 
(Dr. Dobb’s Web Sourcebook, November/ 
December 1995). You can also find Java- 
related information at http://java.sun.com. 
There are differences between Java and 
C++ in both the language and the environ- 





Arguments 


ment. Java does not include familiar C++ 
features such as pointers, preprocessing, 
multiple inheritance, goto, and automatic 
coercion. While I might have liked to keep 
some of these features, Sun makes a case 
for their elimination, and the net effect is 
good. Sun has also added features, such 
as automatic garbage collection. 

Most of the interest in Java currently 
centers around “applets.” Applets are like 
programs, but are loaded and run by a 
Java-enabled browser such as HotJava or 
Netscape Navigator 2.0 beta. A normal 
HTML document can contain a reference 
to an applet that causes the applet to be 
loaded and run (similar to the way images 
are referenced). Applets are given an area 
of the screen to work with and tend (but 
don’t have) to be oriented towards graph- 
ics and GUI. 

Java applications, like applets, are writ- 
ten in the Java language, but are loaded 
and run directly by the Java interpreter 
rather than by a browser. These are usu- 
ally command-line programs, but don’t 
have to be. Un the Alpha3 release of the 
JDK, the HotJava browser was imple- 
mented as a Java application. At this writ- 
ing, there is no HotJava browser available 
for the Beta 1.0 release of the JDK.) I 
chose to make HtmlXlate an application 
instead of an applet because I didn’t need 
to display graphics. It is also useful to be 
able to call the application from within 
other command-line programs (a make 
program, for example). 

When developing in Java, you must 
compile the source, but you don’t have to 
explicitly link it. It will be dynamically 
linked and loaded at run time by the Java 
interpreter. The interpreter also checks the 
code it is loading for errors and virus-like 
behavior. The code can then either be in- 
terpreted or converted to the machine code 
for the current platform. This delayed (op- 
tional) conversion to machine code allows 
any machine and operating system with a 


Dr. Dobb’s Journal, February 1996 





If specialized 
titles weren’t 
so effective, 
we wouldn’t be 
the world’s 
fastest growing 
high-tech 


publisher. 





But we are. 


It’s funny how things can sneak up on you. Like 
Miller Freeman’s strong growth in high-tech magazines. 

As the high-tech world has become increasingly 
specialized, Miller Freeman has quietly assembled an 
outstanding selection of titles to fit this reality. Since 
September 1992, we have added Cadence, Dr. Dobb's 
Journal, Microsoft Systems Fournal, DBMS and OS/2 
Developer. Software Development, OS/2 Magazine, Stacks: 
the Network fournal and Game Developer were launched 
in that same time frame. 

We work hard to identify important markets and 
then deliver magazines with tight editorial focus and 
highly targeted audiences. This gives you access to 
in-depth articles and product reviews—coverage you 
won’t find in broader magazines. 

Our specialized expertise has grown to include 
international marketing and trade shows. Miller Freeman 
is one of North America’s largest producers of high-tech 
events featuring SD East & West, OS/2 World, Autodesk 
University and the Computer Security Conference. 

So next time you’re looking for targeted high-tech 
information, look for a specialized magazine from 


Miller Freeman. 


@if Miller Freeman, Inc. 


A MEMBER OF THE UNITED NEWSPAPERS GROUP 


eso senteanne 
een 
clit \K \ 


eee RO 











Plant Trees 
for America 















A WINDBREAK 
cam Lower healing §——_4 BackyaeD ORCHARD Let 
bls 10-20%. you ghow yout own pruut, 






NAT TIREES Cam be tncohpofated 
yn wind breaks On Sthve wh 
hade fees. 







STREET TREES shad the 
contre and. tebp cool 
the ents neaghhorhocd. 







CO [5 - 35%, 








10 Free Trees 


To Colorado blue spruces, or other 
conifers selected to grow in your 
area will be given to each person who 
joins the Arbor Day Foundation. 

Your trees will be shipped postpaid 
at the right time for planting in your 
area, February through May in the 
spring or October through mid 
December in the fall. The six to twelve 
inch trees are guaranteed to grow, or 
they will be replaced free. 

To become a member and to 
receive your free trees, send a $10 
membership contribution to Ten 
Blue Spruces, National Arbor Day 
Foundation, 100 Arbor Avenue, 
Nebraska City, NE 68410. 

Join today, and plant your Trees 
for America! 





















The National 
7 Arbor Day Foundation 





60 








(continued from page 58) 
Java interpreter to run the application with- 
out recompiling. 

A Java “package” provides a way to col- 
lect a related group of classes. Within the 
package, each class can be public or not. 
Only classes declared public can be used 
outside of a package. When I originally 
wrote Htm/Xiate, I put the classes that pro- 
cess command-line arguments into the 
same package as the rest of the code. Af- 
terwards, I put those classes into a sepa- 
rate package (CmdlnArg) for easier main- 
tenance and reuse. 

Sun defines conventions for command- 
line arguments in the document http:// 
java.sun.com/progGuide/java/cmdLine- 
Args/conventions.html. The document de- 
scribes “word” arguments, “arguments that 
require arguments,” and “flags.” 


e Word arguments are full words that turn 
an option on or off; for example, a typ- 
ical word argument is -verbose. 

e Arguments that require arguments con- 
sist of a keyword followed by addition- 
al information (such as what format to 
output). In HtmlX/ate, for example, the 
keyword is -to and the argument is Réf- 
Writer, TextWriter, or Comment Writer. 

e Flags are like word arguments except 
that they have only one letter and can 
be combined (for example, -vg would 
be two separate flags—v and g). I didn’t 
use flags in Htm/XIate. 


HtmIlXlate requires support for word 
arguments and for arguments that require 
arguments. All arguments should have a 
leading hyphen. If more than one flag 
argument is specified on the command 
line, they can be combined behind one 
hyphen. 











Example 1: Enter these commands to 
compile Java source. 





Example 2: Using the CmdLn Arg package. | 


The Test Program 

At this point, I’m going to assume that you 
have the beta version of the JDK installed. 
If not, you can get it at http://java.sun 
.com/. Although I’ve tested this code only 
with the Windows 95 JDK, it should work 
with other implementations as well. 

To start, pick a directory that will con- 
tain your Java-related files. You will need 
to modify your CLASSPATH environment 
variable to include this drive and directo- 
ry. Below the directory you just created, 
create the subdirectory CmdLnArg (the 
same name as the package), which will 
contain the Java source files presented in 
Listings One through Four (listings begin 
on page 96). 

The directory in which you place the 
source file must have the same name as 
the package, or the Java compiler won't 
know where to look for the classes when 
you use them from outside the package. 
(At first, I gave them different names, 
which resulted in strange compiler errors.) 

To compile the source, enter the com- 
mands in Example 1. (Note that the same 
case must be used for the filenames en- 
tered on the command line.) 

Of the classes being compiled, all but 
the last (Go) are part of the CmdlnArg 
package. The Go class is a test applica- 
tion that uses the package and prints the 
results to STDOUT. To test the program, 
type java Go -in file.in -out file.out. This 
starts the Java interpreter (java.exe) and 
tells it to run the Go application (see List- 
ing Five). The rest of the parameters are 
passed into the Go class for interpretation. 
To see all the parameters Go supports, run 
the application without parameters: java 
Go. (Go is not a reserved name, just the 
name of the class I picked to include a 
static main method.) 


Using the Package 

To use the package in your applications, 
follow the model provided in the process- 
Args method of the Go application. All ap- 
plications must follow the same basic steps: 


1. Create a new instance of ArgProcessor 
and pass it the arguments the applica- 
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(continued from page 60) 
tion received from the interpreter; see 
Example 2(a). 

2. Create and add ArgRegArgType and 
WordArgType instances for each argu- 
ment you want to process; see Exam- 
ples 2(b) and 2(c). Example 2(c) uses a 
shortcut: ArgkegArgType takes a String- 
Buffer as input during construction. Be- 
cause a StringBuffer is a modifiable 
object, the original StringBuffer (input- 
Name) can be modified in step 3. This 
means that your code does not need to 
maintain a reference to the ArgReq- 
ArgType object, but can just check the 
StringBuffer object for the results later. 

3, Call the ArgProcessor.process method to 
update the ArgRegArgType and Word- 
ArgType objects added in step 2; see 
Example 2(d). 

4. Interpret the results. For both WordArg- 
Type and ArgkegArgType, the result is 
stored in a public member named arg- 
Dest. For WordArgType, argDest is a 
Boolean; for ArgRegArgType, it is a 
StringBuffer. Note that for ArgkeqArg- 
Types, you can also reference the String- 
Buffer used to create the ArgReqArg- 
Type (it is the same object that argDest 
references); see Examples 2(e) and 2(f). 


How the Package Works 

The package can be divided into the Arg- 
Processor class (Listing One) and the ar- 
gument type classes that it processes (List- 
ings Two through Four). 

The ArgProcessor class maintains a Vec- 
tor of argument types (vArgs) passed in 
through the add method. Vector is a class 
in the package java.util and is described 
as a “growable array.” When the process 
method is called, each argument passed 
into the application is compared to the 
argument types stored in vArgs (via a call 
to getArg). If an argument type is found, it 
will be set through a call to its set method. 

The getArg method makes use of the 
Enumeration interface, also in the java.util 
package. Java interfaces are meant to pro- 
vide the benefits of multiple inheritance 
without the complications. An interface is 
a type that specifies methods and con- 
stants, but does not specify how the meth- 
ods will be implemented. The Enumera- 
tion interface, for example, specifies the 
hasMoreElements and nextElements meth- 
ods. It is up to the class implementing the 
interface to implement those methods (in 
this case, VectorEnumerator, found in Vec- 
tor.java, which is shipped with the JDK). 

The use of the Enumeration interface 
and Vector class illustrates these features 
of the Java API, but I probably should have 
used the Dictionary class instead. This 
would have made my code simpler and 
probably faster; I know more now about 
the Java API than I did when I started. 


GenericArgeType (Listing Two) is an ab- 
stract class that provides little implemen- 
tation, but defines a method that Arg- 
RegArgType and WordArgType must 
implement. The abstract keyword in the 
class declaration means that it is not pos- 
sible to instantiate an object of this type, 
only a nonabstract subclass. (Even though 
a GenericArgType object cannot be in- 
stantiated, variables can be declared to be 
GenericArgType if they reference objects 
that subclass GenericArgType.) 

The constructor in WordArgType (List- 
ing Three) shows how a superclass con- 
structor can be called. The super(argID) 
line is a call to GenericArgType’s con- 
structor. The set method will toggle the 
Boolean argDest the first time it is called 
and do nothing if called after that. This 
stops argDest from flipping back and 
forth if the user inadvertently specifies 
the argument more than once on the 
command line. 

The constructor for ArgkegArgType (List- 
ing Four) is not much different than the 
constructor for WordArgType. The set 
method is more complicated because it 
needs to use the command-line argument 
after the one containing the leading hy- 
phen. If the user has specified an argument 
requiring an argument and the required 
argument is missing, an exception will be 
thrown. Otherwise, argDest will be set, 
and the index will be incremented by one. 


Conclusion 

One enhancement to the package would 
be the addition of support for flag argu- 
ments. This would not be too difficult and 
would probably require another Vector 
class in ArgProcessor to keep track of the 
flag arguments separately. This would al- 
low a check first for word arguments and 
arguments that require arguments. If that 
check failed, then a check for flag argu- 
ments would be made. 

Another logical enhancement for this 
package might be to warn the user when 
the arguments are not valid. This could be 
done in the process method of the Arg- 
Processor class by adding an Else clause 
at the bottom of the While loop. 

I encourage you to download the JDK 
and work through a few small example 
programs on your own. Java is relatively 
easy to pick up, especially if you are fa- 
miliar with C++. Java also comes with an 
API that includes enough functionality to 
let you concentrate on the interesting parts 
of your program. You may also want to 
watch my page at http://www.inetmi 
.com/~gwhi since I plan on putting up in- 
teresting Java code and information as 
time permits. 


DDJ 
(Listings begin on page 96.) 
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must-have feature in document- 
based applications is undo and redo. 
Most Windows-based word proces- 
i “4. sors, for instance, will faithfully undo 
every command you have entered for the 
past 20 minutes, then perfectly redo all of 
them. The benefit to users is enormous. 
No matter what users do, there is a safe- 
ty net to fall back on. Beginners can forge 
ahead without fear, while advanced users 
can play “what-if? and test the result of 
various changes. 

In this article, I'll present a generalized 
undo/redo mechanism with a history 
length limited only by available memo- 
ry. This undo/redo mechanism will be 
built on top of Spiral, a sample applica- 
tion written under Microsoft Visual C++ 
and the Microsoft Foundation Class li- 
brary (MFC). Note that the code listings 
cannot be compiled by themselves; they 
need additional files, which are provid- 
ed electronically; see “Availability,” page 
3. I’ve tested the Spiral code with both 
Visual C++ 1.52 and Visual C++ 2.2, in 
16 and 32 bit. The executable version of 
Spiral (also available electronically) is a 
16-bit application. 





Jim, a software developer at Turning Point 
Software, can be contacted at jimb@turn- 
ing point.com. 
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To use Spiral, click with the left mouse 
button anywhere in the window, then drag 
out to define a circle. Let up, and the cir- 
cle will be filled with a spiral determined 
by the span angle in the menu option Spi- 
ral:Angle. Changing the span angle will give 
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radically different results. You can also click 
on the line of an existing spiral to select it. 
You can then move the spiral or delete it 
by selecting Clear from the Edit menu. Af- 
ter any of these operations, you can select 
Undo or Redo from the Edit menu. 


To Undo or Not to Undo 

One of the first questions you must ask 
before implementing undo is, “What kinds 
of things can be undone?” It doesn’t make 
sense, for instance, to undo commands 
such as Open or Print. It is necessary to 
identify every action that the user can 
make in an application before answering 
this question. Commands in Spiral can be 
grouped into a variety of categories: 





e File operations (File New, Open, Save, 
Save As, Close Print, Print Setup). 

e View (View Toolbar, Status Bar Window 
New, Cascade, Tile). 

e Application state (preferences, options). 

¢ Document actions (Edit, Clear, Clear All, 
draw spiral, click to select, move the se- 
lection). 


File and Print operations are clearly not 
undoable. Although undoing changes to 
the view or application state might be de- 
sirable, most applications only implement 
undo for actions that change the docu- 
ment. To keep the UI consistent, many 
applications restore the application state 
as a side-effect of undoing document 
changes. For example, changing the span 
angle of the pattern in Spiral affects the 
internal state, but it does not make a vis- 
ible change to the document. Therefore, 
a decision must be made to ignore the 
span angle during undo, or to restore span 
angle changes as part of an undo to the 
document. I take the former approach in 
this article. 

Document actions are clearly eligible 
for undo processing, but even here a care- 
ful check is needed. Making a selection 
does not change the document, so Undo 
Selection should never appear on the 
user’s menu. Moving a selection does 
change the document, so it must be un- 
doable. To decide what to do, ask your- 
self, “What would I, as a user, want to 
happen?” In the case of the move, it would 
probably be best to restore the selection’s 
location, then select it again. 

The decision must also be made about 
undo’s scope. Undo should never extend 
across documents. Each document must 
have its own undo history, otherwise it 
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would be necessary to undo any window- 
focus commands so that the proper win- 
dow would have the focus for each undo 
task. For the same reason, commands such 
as Cascade Windows should also not be 
part of the normal undo mechanism. 

Other decisions are not so obvious. If 
the user undoes a Cut, should the clip- 
board be restored to its previous state, if 
possible? Similarly, if the user saves a file 
using an existing name, should undo re- 
store the previous file? No application I’ve 
seen implements either of these, but from 
the user’s perspective it may be desirable 
to implement this behavior. 

Avoid saving the undo history, particu- 
larly in your master save file. Persistent 
undo histories tend to be confusing to 
users. The undo history can also turn into 
a maintenance headache when the appli- 
cation is revised. 


Assigning Tasks 

The approach I took to creating a set of 
C++ classes to implement undo/redo is 
similar to building construction. A con- 
struction crew has specialized workers, 
each of whom performs one particular 
task. Each worker is told what to do by a 
foreman. The foreman may not know how 
to do any of these tasks, but he does know 
how to manage the construction effort. 

For undo/redo, the job is to put together 
a document instead of a building. Work- 
ers will be needed to move selections, cre- 
ate spirals, clear spirals, and so on. Each 
task will be represented by a class derived 
from a base class CTask. The CTask ob- 
jects will be worker objects that perform 
certain tasks. Each worker class will also 
know how to undo its task. 

The class C7ask (see Listing One, list- 
ings begin on page 100), is defined as an 
abstract base class: It represents what ev- 
ery task should look like but is not itself 
a real task. Each class derived from CTask 
has a constructor to describe it and a de- 
structor to clean up any private data. Ev- 
ery time the user does something that 
could be undone, a new instance of a class 
derived from C7Task will be created. For 
example, suppose that the user draws a 
new spiral. The CCreateSpiralTask class 
(see Listing Two) knows how to add a 
new spiral to the document. When the user 
releases the button and the spiral is fin- 
ished, a new task is created. The only thing 
interesting about a new spiral is the spi- 
ral’s data, so this information is passed to 
the task in the constructor: 


CCreateSpiralTask pCreateSpiralTask 
=new CCreateSpiralTask(pSpiral);. 


The newly created task stores this in- 


formation in private member data. Each 
instance of the class will have its own data. 
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Note that CCreateSpiralTask, like all tasks, 
has no default constructor. It is not pos- 
sible to create a task without knowing all 
the details of the task. 

Who should start this task? Only the 
foreman can do that. The foreman man- 
ages all tasks. Listing Three presents the 
CForeman class. The foreman is respon- 
sible for executing tasks and keeping track 
of the task history. The foreman is the 
heart of the undo/redo mechanism. To re- 
quest that a task be executed, Swbmit- 
Task() in CForeman is called: m_Fore- 
man.SubmitTask(pCreateSpiralTask),. 

To execute the submitted task, CFore- 
man calls the task’s Do() member func- 
tion. CForeman should be the only ob- 
ject that calls any task’s member functions. 
The foreman has sole responsibility for 
keeping the undo/redo history consistent 
with the document. If any changes are 
made to the document without the fore- 
man having a corresponding task, then 
the tasks in the history can become con- 
fused and crash the application. In Submit- 
Task(), CForeman immediately executes 
the task by calling: pCreateSpiralTask 
Do(m_pSpiralView);. If the task succeeds, 
CForeman adds the task to the end of its 
history list. The foreman implements the 
command history simply by keeping track 
of which tasks were called. 


Managing the Command History 
The command history is maintained as a 
linked list of tasks that is managed some- 
what like a stack. The MFC collection class 
CObList with the template CTypedPtrList 
quickly provides the needed implementa- 
tion. (I’ve “faked” the template C7yped- 
PtrList in the Spiral source for Visual C++ 
1.5x.) CForeman also keeps a pointer to 
the last task executed. Undo moves the 
pointer backwards in the list, and redo 
moves the pointer forward, see Listing Four. 
Let’s take an example in which the user 
draws two spirals, makes a selection, then 
selects Clear from the Edit menu. At this 
point the task list looks like this (remem- 
ber, making a selection is not undoable by 


itself): 


1. CreateSpiralTask #1. 
2. CreateSpiralTask #2. 
3. ClearSpiralTask. 


The last task executed is task 3. Now 
the user selects Undo. CForeman handles 
the undo by calling the Undo() member 
function of the last executed task with a 
pointer to the current document: pTask > 
Undo(m_pSpiralDoc); // pTask points at 
task #3. 

Now that task 3 has been undone, the 
last task executed is task 2. The user se- 
lects Undo again. CForeman calls the 
Undo() member function of task 2. The 
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last-task-executed pointer is moved back 
to task 1: pTask ~ Undo(m_pSpiralDoc); 
// pTask points at task #2. 

Next the user hits Redo. CForeman calls 
the Do() member function of task 2 again 
and advances the pointer for last task ex- 
ecuted back to task 2: pTask>Do(m_ 
DSpiralDoc); // pTask points at task #2. 

Finally, the user creates another spiral. 
CForeman handles the new task by throw- 
ing away every task that is waiting to be 
redone. In this case, only task 3 is thrown 
away. The task is removed from the linked 
list of tasks and discarded with the C++ 
delete operator. Because the destructor for 
CTasks is virtual, the object pointed at by 
pClearSpiralTask will have the opportu- 
nity to properly clean up. 

The undo/redo mechanism is now ba- 
sically functioning. What’s left is to write 
a lot more tasks and to properly update 
the user interface. 


Inside a Task 

The class for each task must keep track 
of enough data to be able to complete the 
task without querying to the current view 
and, preferably, without querying the ap- 
plication state. The current view may not 
be queried because the user could select 
Redo from within any view. By not query- 
ing the application state, Redo can be ex- 
ecuted without producing a different re- 
sult if the application state changes. 

All of the information required to com- 
plete a task should be part of the con- 
structor for the task. For example, CC7reate- 
SpiralTask takes a completed spiral as its 
argument. The completed spiral contains 
information about the center, radius, and 
span angle. If CCreateSpiralTask's con- 
structor did not include the span angle, 
then the spiral would change if the user 
chose the Spiral:Angle menu option be- 
tween the Undo and the Redo. 

The class for each task must also keep 
track of enough data to be able to undo 
the task. In the case of CCreateSpiralTask, 
Undo() can retrieve the last spiral from 
the spiral list because the last spiral cre- 
ated is always at the end of the spiral list. 


CClearSpiralTask is the opposite of CCre- | 


ateSpiralTask. After Do(), the task re- 
members the deleted spiral and its posi- 
tion in the class’s data area. 

A task can be deleted at any time, so it 
is important to keep track of whether a 
task actually owns any objects it points at. 
If CCreateSpiralTask tries to delete its spi- 
ral after inserting the spiral into the doc- 
ument, the application will crash. Spiral 
solves this problem by making each task 
modal. The modes are “able to Do()” and 
“able to Undo()”. After CForeman calls 
Do(), it must call Undo) before calling 
Do() again. In CCreateSpiralTask, after 
placing the spiral object back in the doc- 
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ument in Do(), the task’s pointer to the 
spiral is set to NULL. If the pointer is not 
set to NULL in the task, then CCreateSpi- 
rallask’s destructor and the document’s 
destructor will both try to free the spiral 
object. Listing One shows, for each mem- 
ber variable, whether the member vari- 
able is needed for Do() or for Undo). 


Updating the Menus 

I was always impressed by applications 
that were able to give descriptions of the 
actions on the undo and redo history. With 


The command 
history is 
maintained as a 
linked list of tasks 
that is managed 
somewhat like 
a stack 





the implementation of undo/redo de- 
scribed in this article, this functionality is 
easy to implement. 

All of the code necessary in the view 
to update Undo and Redo in the Edit 
menu is in Listing Five. The corresponding 
code in CForeman is shown in Listing 
Four in the member functions GetUndo- 
Description() and GetRedoDescription( ). 
CForeman uses its last-task-executed 
pointer to get a pointer to the next task 
to be undone or redone. Each task has a 
virtual function called GetDescription() 
that returns a short description of the task. 
CForeman returns this result from Get- 
Description(), or the empty string if no 
task is waiting. 


Managing Multiple Documents and Views 
In an application that supports multiple 
documents and/or multiple views, one 
problem is how to maintain separate undo 
histories. CForeman uses no global vari- 
ables, so multiple instances of CForeman 
can be created. To implement multiple his- 
tories, CForeman is placed as a member 
of the CSpiralDoc document class. This 
way there will be a separate undo histo- 
ry for each document, and multiple views 
of the same document will share a single 
undo history. Functions that need to call 
CForeman will be able to access the class 
through a pointer to the document. In as 


much as I’ve already defined undoable op- 
erations to be those that affect the docu- 
ment, I can guarantee that a pointer to the 
current document’s foreman will always 
be available when I need it. 

Spiral supports multiple views of the 
same data, so any time the document is 
changed, all views must be updated. MFC 
provides a function called UpdateAll- 
Views() as part of the document class. 
Hints are used in Spiral to describe spe- 
cific spirals or rectangles to be updated. 
These hints optimize the redraw handling 
and prevent excess redraws across the 
Views. 

Tasks are called by CForeman with a 
pointer to the document because undo/ 
redo tasks work on the document, not the 
view. Views are only convenient rep- 
resentations of that document. With one 
exception, tasks must completely ignore 
any view information because the current 
view could be closed or modified the next 
time the task executes a Do() or an 
Undo(). The exception is that the current 
view should automatically scroll to make 
whatever was undone or redone visible 
to the user. 


Updating the Modified Flag 

Very few Windows apps recognize when 
a document has been returned to the orig- 
inal state. With the undo history present- 
ed here, it is possible to determine that 
the user has undone all changes and to 
reset the modified flag to False. This pre- 
vents the user from typing a key acci- 
dentally, pressing Undo, and still having 
the application ask if it should save the 
changes. 

This feature can be implemented safe- 
ly by throwing away the undo history 
when the user saves. This is the way that 
Visual C++ 2.x and most other applica- 
tions are implemented. Word for Windows, 
on the other hand, keeps the undo histo- 
ry after the document is saved but cannot 
detect that the user has undone all 
changes since the last save. 


Adding Undo/Redo to Existing Apps 
Many existing MFC applications can eas- 
ily be modified to support this mecha- 
nism. User actions are typically imple- 
mented as part of the view. The view ends 
up having numerous member functions, 
each of which takes care of one user- 
interface action. To implement an undo/ 
redo history, each of these member func- 
tions is pulled out of the view and made 
into a task class. The key to success is 
making sure that anything the user can 
do that modifies the document is made 
into an undo/redo task. 


DDJ 
(Listings begin on page 100.) 
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Gil Gameiro 


s any coffee aficionado will tell you, 
there’s more to a good cup of cap- 
puccino than freeze-dried flakes and 
hot water. Today’s coffee makers, in 
fact, do just about everything but drink the 
java for you. The espresso machine in Fig- 
ure 1, for instance, grinds beans, compacts 
a water, and serves a good strong cup of 
espresso — then discards the grounds in 
a garbage drawer. 

However, what really makes this es- 
presso maker unique is that I’ve con- 
nected it to a Novell network and con- 
trol it with a Windows application I call 
“Expresso Maker.” Figure 2 shows how 
the application lets you remotely select 
a coffee maker, heat the water, specify 
the serving size and strength, make the 
coffee, and gather real-time information 
about the process and statistics about 
usage — all across the network. The 
program provides system administration 
feedback for the resident “javameister’; 
see Figure 3. 





Gil is an engineer with Novell’s NEST group. 
He can be contacted at gil_gameiro@ 
novell.com or hitp.//jwww.vti.com/~bird/. 
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Just Another Embedded System 
In many ways, the Expresso Maker system 
is nothing more than a typical, networked 
embedded system. The system designer 
has to provide a secure connection, make 
it possible for the supplier to perform di- 
agnostics and maintenance tasks, and en- 
able a broker service so that end users can 
locate any given item/service, check for 
availability, and find the closest supplier. 
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Figure 1: Off-the-shelf espresso maker 
that’s modified for network control. 


At the heart of the Expresso Maker ap- 
plication is Novell’s Embedded Systems 
Technology (NEST), which is designed to 
let you incorporate network protocols and 
client services into embedded systems. 
Even though my application runs under 
Windows, I could have written it for OS/2 
PM because the library for NEST remote 
clients is given in source format. The de- 





velopment of the NEST target is hosted on 
whatever environment an operating-system 
vendor supports. For WindRiver’s VxWorks 
on an AMD29K processor, for instance, I 
use a SunSPARC workstation. For FlexOS, 
I use DOS and Watcom C. Byte-order de- 
pendencies and alignment differences are 
therefore reconciled, and all system-level 
functions for memory and process man- 
agement and event, timer, interrupt, and 
I/O services are specified in an API that’s 
available for implementation on any ker- 
nel or operating system that supports pre- 
emptive multitasking. 

The NEST architecture consists of the 
following: 


e Application layer, which hides the dif- 
ferences between OSs by providing an 
easy-to-port set of common OS services. 

e NetWare services layer, which provides 
access to NetWare services (queue, 
bindery, directory, connection, file, mes- 
sage, auditing, and authentication ser- 
vices). 

e Connection layer, which contains the 
protocol stacks and the underlying 
“plumbing” that interconnects every net- 
work node. It provides the connection 
between the Services layer and the phys- 
ical network. 


Developing NEST-based applications 
(like Expresso Maker) requires the NEST 
SDK. This toolkit is DOS based, although 
the SPX and IPX test tools included with 
it are Windows hosted. Also included is 
a Print test tool for testing embedded NEST 
printers, which requires a server with Net- 
Ware 3.x or 4.x, a Windows workstation, 
and the embedded printer to test. 
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(continued from page 68) 

The NEST requester supports — but 
does not require — connection to NetWare 
3.x and 4.x servers. It includes support for 
packet signatures, packet burst, RSA login 
authentication, and directory services. 
NEST also supports the NetWare protocol 
stack. C source for SPX/IPX, LSL, and 
MLID is based on the ODI model stan- 
dard with open interfaces to the transport 
services for applications and the MLID to 
accommodate different media types. The 
LSL supports Ethernet 302.2, Ethernet 
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Figure 3: Expresso Maker sysadm screen. 
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EXpresso 


802.3, Ethernet II, and Ethernet SNAP 
frame types. The next version of NEST will 
also come with source code for IP, TCP, 
UDP, SNMP, NP, IPX, SPX, NCP, and NDS 
protocols. 

To connect the off-the-shelf coffee mak- 
er to the network, I had to design, build, 
and install a custom interface card. The 
original espresso maker (a “Super Auto- 
matica” model from SAECO, an Italian 
company) was designed around a me- 
chanical sequencer. I had to redesign the 
coffee maker from the ground up, since 
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it did not provide the easy hooks need- 
ed for microprocessor-based embedded 
devices. At the heart of the hardware is a 
286-based board (in the PC104 form with 
1 MB of RAM; I could have used less but 
this amount of memory was on board) 
and a 27C010 256-KB EPROM. 

For the network adapter, I used an 
AMD79C960 (PCNet/ISA) chip, mainly 
because it is a one-chip adapter and 
NEST provides a sample HSM that can 
be modified to support the PCNet/ISA. 
The network chip does not require ad- 
ditional RAM and needs only a little de- 
coding logic, a 256-byte EPROM (most- 
ly for the MAC address), and the line 
transformer. 

Finally, I designed an J/O interface 
based on an 8255 Programmable I/O 
chip, an 8253 3-channel counter timer 
(to count the debit of water being 
served), a 2X16 LCD display, some push- 
buttons, and six opto-triacs with zero- 
crossing detection. These opto-triacs are 
boosted by TO-220AB case triacs to con- 
trol the power elements in the maker— 
the grinder, drop-dose solenoid, a mo- 
tor that compacts the grounds in a wafer, 
a pump and gate for the water, and a 
water heater that keeps the machine 
ready at all times to serve a cup of brew 
in seconds. 

I used FlexOS Lite, a multitasking, real- 
time operating system from ISI (FlexOS 
was originally developed by Digital Re- 
search). Since ISI’s implementation does 
not provide ROMing tools, I had to write 
a utility that links the compiled operating 
system with the NESTed application, com- 
presses it, and generates an Intel Hex file 
along with a loader header. The loader 
code presents a valid signature to the ROM 
POST that initializes it. It then handles the 
boot process by loading the operating sys- 
tem along with its NEST driver application 
without returning. 

Even with all this, the most difficult part 
of the job was cutting a square hole on 
the thick metal back of the coffee maker 
to insert the RJ45 10baseT network con- 
nection. 


Building the Expresso Maker Program 

Central to any NEST app is the NEST Pro- 
tocol (NP), a “light” protocol especially 
developed for embedded devices allow- 
ing for secure remote configuration and 
operation. NP’s design puts the connec- 
tion burden on the remote client, mini- 
mizing the code on the NEST side, while 
maintaining a secure connection based on 
a login with a randomly generated access 
key and encrypted password. Moreover, 
each packet contains a running public- 
key signature. NP works on top of the IPX 
layer to minimize the required protocol 
stack. It wants less than 10 KB of code on 
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VxWorks Developers! 


What is different about this screen shot of VxWorks? 
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(continued from page 70) 

the embedded device. This protocol does 
not provide real-time management. It was 
aimed at browsing and maintaining set- 
tings of predefined configurable items 
(given that the logged-in user has rele- 
vant access rights). 

When building Expresso Maker, I want- 
ed NP to transfer information other than 
remote-configuration data. Fortunately, I 
found an undocumented function, NPReg- 
isterClassHandler( ), used by the remote 
configuration compo- 
nent to register its ser- 
vices with the NP dae- 
mon. The call requires 
a pointer to a function 
(void (*)(NPConnec- 
tion*, ECB*, ECB*)) 
and an integer that is 
a function number of 
NP to manage. 

NP is composed of 
an NPHeader and IPX; 
see Listing One (list- 
ings begin on page 
104). The Function 
and SubFunction fields 
give the type of in- 
formation carried by 
the data following the 
header. When the NP 
daemon receives a request from a remote 
client, it matches the Function number to 
known services and normally discards the 
packet if the service is unknown— unless 
it matches a user-defined registered han- 
dler (also confusingly referred to as “Class 
Number” in the source comments). List- 
ing Two handles my extended class of 
services. 

The ClassHandler of incoming data is 
rather simple, but its expected behavior 
is rather tricky: It takes a pointer to a Con- 
nectionHandle, a structure maintained by 
the NP for every logged-in and active con- 
nection. (I strongly recommend not mod- 
ifying any of the contents of this structure, 
as it is apparently present for the Class- 
Handler in charge of the login and au- 
thentication process.) 

The two remaining parameters are 
pointers to event control block (ECB) 
structures that send and receive network 
packets. The first ECB* is the received 
ECB for the request, and the second is 
an ECB preallocated and formatted for a 
reply to the request. You can assume that 
the ECB_Fragment{1/.FragmentAddress 
will always contain the full NP data, in- 
cluding the header, and that any re- 
maining lower-level protocol (IPX) would 
be taken in the ECB_ 
FragmentlO]. Sup- 
posedly, future re- 
leases of NP will run 


The NEST 
architecture consists 
of an application 
layer, a NetWare 
services layer, and a 
connection layer 


well as IPX. For now, however, forget 
about the protocol used, since it has been 
preformatted by the NP daemon. 

The preallocated buffer for the NP data 
is big enough to contain the largest amount 
of data (504 bytes) supported by NP. Al- 
though IPX/Ethernet can transmit up to 
1514 data bytes, Novell limited the proto- 
col size to a total of 576 bytes because NP 
was designed to remain as small as pos- 
sible; as such, it cannot disassemble and 
reassemble large packets. In fact, 576 is 
the largest number of 
bytes that can be trans- 
mitted between two 
IPX/Ethernet nodes in 
a heterogeneous net- 
work (ARCNet suffers 
this limit, for example). 
All together, SNAP (a 
larger frame type than 
most common 802.2), 
IPX, and the NPHead- 
er make up close to 
504 bytes. 

The class-handler 
routine extracts the 
pointer in the ECB’s 
Fragmeni{1/by casting 
it to a pointer to an 
NPRequestBuffer. The 
SubFunction number 
in the NP header allows routing and pro- 
cessing of the request made by the re- 
mote client. 


A Few Caveats 

Since NP was designed to be small and 
secure, it combines system-maintenance 
packets with user data. In other words, 
when the remote client sends a request to 
be handled by the class handler, the sys- 
tem acknowledgment is also the packet 
that will contain the user-reply data should 
the request generate data on the reply (un- 
like SPX). 

Moreover, the way the class handler re- 
trieves the number of OEM data bytes in 
the request and specifies the amount of 
data in the reply is still awkward: That’s 
probably why NPRegisterClassHandler is 
undocumented. 

Example 1 (from my class handler) 
shows how the amount of data in the re- 
quest is retrieved. The field length of the 
NPHeader is converted to the CPU native 
order using the NSwapHiLo16() macro. 
The result is then increased by 4 and sub- 
tracted from SJZEOF_NPHeader. The rea- 
son for the addition is that the Length field 
describes the total length of the NP pack- 
et excluding the first two fields of the 


int msgSize = NSwapHiLo16(reqECB->Header.Length) ; 


msgSize -= (SIZEOF_NPHeader - 4); 





on top of UDP as Example 1: How data is retrieved. 
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(continued from page 72) 
NPHeader (that is, CheckSum and Length). 
Subtracting SIZEOF_NPHeader (a define 
equal to the actual size of the NPHeader) 
gives the amount of data bytes placed in 
the packet for OEM usage. 

Another caveat concerns declaring the 
amount of data attached to the reply. 
The class handler must not set the 
Length field of the NPHeader in the re- 
ply ECB; it must instead set the actual 
size of data to be transmitted plus SIZE- 
OF_NPHeader in the ECB_Fragment{1] 
_FragmentSize. The NPDaemon will 
modify the NPHeader’s Length field to 
reflect the proper size. 

The FragmentCount must be set to 2; 
otherwise no response is generated. This 
step is mandatory for proper use of the 
undocumented ClassHandlers: Failure to 
do so will make the remote client retry 
the same request repeatedly, causing 
your handler to be called until a time- 
out happens. 

A last rule of thumb is to process the 
packet as quickly as possible: Ideally, this 
should take no more than 200 ms or so 
(if no error code is to be returned because 
the action takes longer, a success should 
be sent right back with no data, and some 
other mechanism should be used for re- 
porting the actual error). 


Inside the Expresso Maker Code 

The class-handler code extracts the Sub- 
Function number in the NP header and 
routes the request to the appropriate code, 
which returns an error code. The NSwap- 
Hilo16() macro is defined to convert a 
16-bit value from the CPU native format 
to HiLo or vice versa: It swaps or does 
nothing, depending on whether LIT- 
TLE_ENDIAN is defined. You can use your 
data the way you want, but NPHeader 16- 
bit data is carried in the HiZo format for 
portability. 

The error code returned by my func- 
tion is placed on the Status field of the 
NPHeader in the reply ECB. There, too, 
the NSwapHilo16() macro is used for 
portability. The error code must match the 
philosophy of the NEST protocol: 0 is suc- 
cess, 70xx is an error from NP, 71xx is an 
error from the remote configuration. For 
errors in my module, I used 76xx and kept 
the low byte in predefined NP error code. 

When SubFunction is beyond what you 
expect, it is reasonable to use the error in 
the NP range (NPER_-UNKNOWN_RE- 
QUEST), as this is what NP would have 
otherwise returned. 

The next challenge was determining 
how to notify the remote client of an asyn- 
chronous event, provided NP is based on 
a client request (NP ack+reply scheme). 

Novell tipped me that the Sequence 
number was also to be used when the 
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NEST side takes the initiative to notify a 
remote client, along with a flag 0x1000 set 
in the NP Flags field. This way, it can no- 
tify the client’s library that a packet is not 
an ack/reply and requires a reply from 
the client. The Flags are set with that same 
bit, plus another 1, to show that it is a re- 
ply: That is how the sequence number is 
matched to either the previous request or 
previous notification. 

Novell plans to ship this code with 
NEST’s next release; unfortunately, when 
I originally designed this project, I had to 


The main purpose 
of NEST is to 
provide more 

services so that a 

network device 
actually becomes 
a “server” 


write it myself. The modification of the 
client library was rather easy, requiring 
an existing internal function (makeAck- 
Packet) to reply (without forgetting to 
turn on the extra bit NP_FLAG_IS_ACK 
with the appropriate swapping macro on 
the client side) and the use of the Win- 
dows PostMessage() API. The modifica- 
tion of the NEST side was a little harder, 
as I had to create Timeout and Retry for 
every asynchronous request. We’ll dis- 
pense with the low-level details of creat- 
ing asynchronous retries on the NEST side 
without a specific thread because Novell 
plans to provide this functionality in fu- 
ture versions of NEST. 

The client deals with sending OEM ex- 
tended requests by using a DLL call Cun- 
documented at the time): NPSendEx- 
tendedNP(ConnHandle*, EDB*) that 
allows for sending extended NP packets 
on an existing connection. It takes a 
ConnHandle* (obtained by the NPLogin- 
ToNestDevice() API call) and an EDB* (a 
new structure). The EDB will probably 
be used for two tasks in future releases 
of the PEST protocol library: describing 
an extended packet for the call I am 
about to explain, and notifying events 
asynchronous to the application that’s us- 
ing the DLL (ike the code I wrote on the 
NEST side). Toward this end, the pro- 
gram must post a few EDBs waiting for 


asynchronous events using the NPLis- 
tenForEDB() API call. (When I looked at 
the DLL code, NPListenForEDB() was in 
an #if0 condition block and I had to en- 
able it.) 

For now, we need consider only the 
following fields in the EDB: edbFunc- 
tion and edbSubFunction must be filled 
with the functions we made our NEST 
device aware of, while edbDataBlock[] 
and edbDataSize contain eventual user 
data to attach to the NP system header. 
No special care is required with the byte 
ordering of edbFunction and edbSub- 
Function: The DLL swaps those two to 
network HiLo order. However, the data 
block is up to the OEM. If your NEST 
device is based on, say, an AMD29K 
CPU and the client is Windows, you have 
to swap entities other than bytes. If you 
stick to the network order (HiZo format), 
you'll always know what you are look- 
ing at, even when you use a LanAlyzer 
to look at network traffic. 

According to Novell, the current re- 
lease of the NPDLL library will complete 
all the calls synchronously, so the EDB 
used for an extended OEM NP message 
will come back modified with the an- 
swer from the NEST device (if the lat- 
ter generates user data attached to the 
NP system ack). The next version of the 
DLL will complete an NPSendExtended- 
NPC by posting an EDB message back 
to the application instead of modifying 
the one used for the request. This 
change means Expresso Maker will be 
incompatible with future versions of the 
NPDLL, which will allow you to work 
synchronously or asynchronously by re- 
questing the operating mode after log- 
ging into a NEST device (with the NP- 
SetConnFlags() API, which is also in an 
#if 0 block in the preliminary version 
of the DLL). 


Conclusion 

The main purpose of environments such 
as NEST is to provide more services so 
that a network device actually becomes 
a “server.” Such a device does not nec- 
essarily need to authenticate to a tree, 
but rather to exchange data and services 
with a remote client (which could even 
be another embedded device). NP is a 
small, reliable, secure protocol that can 
be leveraged to provide more than just 
remote configuration without paying the 
price of large code. 
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Derek Brown and Martin Hall 


he Windows Sockets specification has 

made Windows a viable network- 

software platform. WinSock 1.1, for 

instance, provided Windows with a 
standard TCP/IP networking API. This led 
to an explosion of network-enabled soft- 
ware for the PC, which coincided with the 
popularity of the Internet and World Wide 
Web. WinSock 2.0 builds on the earlier 
specification by providing true multipro- 
tocol support, implementing socket shar- 
ing, and offering significant performance 
enhancements. Still, the upcoming Win- 
Sock 2.0 retains binary and source com- 
patibility with WinSock 1.1. 

To better support wireless, ATM, and 
ISDN networks, for example, WinSock 2.0 
has added quality-of-service features to 
give you greater flexibility and control over 
a multitude of network media. These fea- 
tures make it possible for the application 
to discover bandwidth and latency for 
ATM, ISDN, and other types of networks. 
This information is particularly useful to 
multimedia applications. 


Derek has done extensive development 
work on Windows-based communi- 
cations software. He can be reached at 
db@stardust.com. Martin is cofounder 
and CTO of Stardust Technologies, and 
can be reached at martinh@stardust.com. 
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The WinSock 2.0 spec also includes ex- 
plicit multipoint/multicast support. Al- 
though some vendors provide this with 
WinSock 1.1, the spec doesn’t require it. 
In addition to the window-based, asyn- 
chronous notification of network events 
in WinSock 1.1, WinSock 2.0 has event- 
driven asynchronous notification and sup- 
ports overlapped I/O. 

One networking problem addressed by 
WinSock 2.0 involves a variety of different 
name-resolution services. WinSock 2.0 
allows a program to ask which name- 





resolution services are available (for ex- 
ample, DNS or X.500) and then ask a par- 
ticular name service to resolve a particular 
name. This allows WinSock 2.0 apps to 
work comfortably in heterogenous net- 
work environments. 

WinSock 2.0 features such as over- 
lapped I/O and asynchronous-event ob- 
jects rely on operating-system functional- 
ity not found in 16-bit Windows. For that 
reason, WinSock 2.0 will be initially sup- 
ported only in Windows 95 and Windows 
NT. Implementing WinSock 2.0 on 16-bit 


Windows and Win32s will require emu- 
lating some services of the newer Win- 
dows platforms. 

In this article, we'll describe how to get 
maximum performance from WinSock 2.0 
applications. In particular, we'll focus on 
extremely fast network-file transfers, where 
the transfer rate is limited only by the 
speed of the network connection, the 
speed of the underlying media, and the 
overhead of the operating system itself. 
In the world of WinSock, this is as fast as 
it gets. 

To achieve this performance, we'll take 
advantage of two features new to WinSock 
2.0: event objects and overlapped I/O. 


Event Objects and Overlapped I/O 
Event objects are used for thread syn- 
chronization. Suppose you have two 
threads, one of which relies on some com- 
ponent of the other thread to complete. 
By calling one of the Win32 event-object 
routines, the first thread can be suspend- 
ed until the second signals an event. The 
event is a Windows handle with two states, 
signaled or nonsignaled. When the first 
thread requires processing in the second, 
it blocks and waits for the event. When 
the second thread completes the neces- 
sary processing, it signals the event, al- 
lowing the first thread to continue. 

In the following discussion, our file I/O 
thread will be blocked until a particular 
read or write completes. An event object 
is associated with an asynchronous file 
I/O call, then WaitForSingleObject() or 
WaitForMultipleObjects() is called. The 
thread is truly blocked until something — 
in this case the completion of the I/O— 
signals the event. Once the event is sig- 
naled, the blocked thread resumes. 

One common use of event objects is 
synchronizing a file I/O thread when us- 
ing overlapped I/O. Normally, file I/O op- 
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(continued from page 706) 

erations require multiple buffer copies. 
When an application calls write(), the 
buffer passed into write() is copied in- 
ternally, and the write() call completes. 
The internally copied buffer is (eventual- 
ly) written to the file system. Overlapped 
I/O saves a buffer copy by using the buffer 
passed to WriteFile() directly, rather than 
making an internal copy. Since the oper- 
ating system is using the application’s 
buffer rather than an internal one, the op- 
erating system must notify the application 
when the I/O is complete. Until that time, 
the application may not and should not 
change the buffer. In Win32, that notifi- 
cation is done by signaling an event. 


Fast Network I/O 
The program we'll present here provides 
the meat of what could be a generic FTP 
client and server. On the server side, the 
program needs to open a file, read it, send 
it, then close it. On the client side, the pro- 
gram needs to open the file, read from 
the network, write the file, then close it. 
To perform this operation, we first need 
a connection from client to server. On both 
ends of the connection, the socket needs 
to be created with WSASocket() to enable 
the overlapped I/O. We are using a 
stream-based protocol and, for simplicity, 
assume that we want TCP. On the server 
side, we then bind() to a known port 
number for the client to connect to. The 
client can bind() to any available address. 
Our client resolves the host name using 
the generic TCP/IP addressing scheme. 
(This sample code doesn’t delve into the 
various address families supported by 
WinSock 2.0.) After successfully binding 
to a local address, the client calls (a block- 
ing) connect). Once the connection is es- 
tablished, it’s time to actually send the file. 
With WinSock 1.1, the client would just 
enter a tight loop, reading from the net- 
work and writing to the file system as fast 
as it could. However, each successive call 
to recu() would not be initiated until the 
previous block could be written to disk. 
Each successive write call could not com- 
plete at least until the buffers were copied 
internally; see Listing One (listings begin 
on page 105). With WinSock 2.0 and the 
Win32 overlapped I/O mechanism, we 
can dramatically increase the performance. 
The WinSock 2.0 client code begins in 
the function get_file_from_server() in List- 
ing Three. For simplicity, the connection 
is established using the old-style blocking 
routines. A buffer pool is created into 
which the file is read and from which the 
file writes will be sent. An event object is 
created for each buffer in the pool. By as- 
sociating each buffer with an event, we 
ensure that each thread will be able to 
proceed in the proper order. Once the 
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buffer pool is created and initialized, we 
begin the process by calling WSARecv() 
with each buffer/event object pair. 

At this point, the operating system be- 
gins filling the buffers. Next, we create the 
NetworkThbread thread for handing the 
completion of file I/O. That thread is 
blocked, waiting for the event associated 
with the first buffer to be signaled. When 
the first network receive is complete, we 
create FileThread, a second thread for 
completion of file I/O. We wait to create 


Overlapped I/O 
avoids the overhead 


of a buffer copy 


the second thread to ensure the threads 
are properly synchronized. When the first 
buffer is filled, the associated event will 
be signaled and the WSAWaitForMultiple- 
Evenis() will return. Since we want to read 
the file sequentially, we just wait for the 
event object associated with each buffer 
in turn. 

As each buffer is filled, WSAWaitFor- 
MultipleEvents(_) returns (we're only look- 
ing for one event at a time, but you could 
use the same call to wait for multiple 
events). The buffer we originally sent to 
WSARecv() is now full, and we want to 
write it to disk. By using WriteFile(), the 
buffer will be sent as is (without a copy 
into a buffer internal to the file system), 
and we'll wait for completion in our file 
I/O thread. As each file operation com- 
pletes, the event associated with that buffer 
is signaled. We can then send that buffer 
back into the pool of buffers waiting to 
be filled from the network, again calling 
WSARecu(). Using this rotating buffer pool, 
we can implement a write-behind scheme 
that allows the operating system to read 
and write at its earliest convenience. 

The server code also starts by opening 
a socket, bound to a local address. We /is- 
ten() for incoming connections, then en- 
ter a blocking accept(). When the client 
calls connect(), the server accept()s the 
incoming connection and we're ready to 
send the file. 

As with the client, the WinSock 1.1 serv- 
er in Listing Two reads and sends blocks 
of data one at a time. The write to the net- 
work layer can’t begin until the data is 
read from disk. Again, time is wasted in 
internal buffer copies, as data is first writ- 


ten into the kernel-disk buffers, then into 
the user buffer, and finally into the pro- 
tocol stack’s buffers waiting to be sent. 

To speed things up, the server code in 
Listing Four uses the same— but re- 
versed — procedure as the client code. 
The setup procedure send_file_to_client() 
first establishes the connection with the 
client. We create and initialize the buffer 
pool and call ReadFile() with each buffer/ 
event object pair. After the first event is 
signaled (from the first call to ReadFile()), 
we Start the thread to handle the network 
I/O notifications. Again, to make sure the 
threads start out synchronized, we don’t 
start the NetworkThread until the first file- 
system read is complete. As file system 
reads complete, we'll initiate WSASend() 
calls to send those buffers straight to the 
network layer. 

The most notable improvement would 
be to take advantage of the multiple pro- 
tocol support WinSock 2.0 offers. In this 
code, we established the connection based 
on the familiar IP constructs and resolved 
the host names using DNS. The new Win- 
Sock 2.0 name/services resolution routines 
let you perform transport-independent 
calls that use IPX/SPX, AppleTalk, DEC- 
Net, or any other protocol for which a 
WinSock 2.0 namespace service provider 
exists. 


For More Information 

One way to follow (or contribute to) the 
WinSock Group is to join a mailing list. 
Send e-mail to majordomo@mailbag.in- 
tel.com with subscribe list in the body of 
your e-mail. /ist can be either winsock-2 
or winsock-hackers. The winsock-2 list is 
the focal point of net-based discussion of 
WinSock 2.0. The winsock-hackers list is 
a hang-out for WinSock 1.1 programmers, 
although a lot more discussion happens 
in the WinSock newsgroups. 

Among the newsgroups that provide 
WinSock 2.0 information are alt.winsock 
(general WinSock discussion) and alt.win- 
sock.programming (programmer- specific 
WinSock discussions). WinSock infor- 
mation is also available at ftp://ftp.star- 
dust.com/pub/winsock/ (WinSock 1.1 and 
2.0 documents, freeware/shareware pro- 
grams, and so on), http://www. intel.com/ 
IAL/winsock2/ (WinSock 2.0 information), 
and ftp://ftp.cica.indiana.edu/pub/pc/ 
win3/winsock/ (freeware and shareware 
programs). 

Finally, the World Wide Web sites pro- 
viding WinSock information include http:// 
www.stardust.com, http://www. intel.com/ 
TAL/winsock2/index.html, http://sun- 
site.unc.edu/winsock/, and http://www 
-microsoft.com/pages/developer/winsock/. 


DDJ 
(Listings begin on page 105.) 
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while back I wrote a fairly complex 
system for storing and retrieving 
petroleum-reservoir simulation X/Y 
plot output. Using only a compiler, 
it took me over a year to develop the ap- 
plication, which consisted of about 30,000 
lines of C++ code. 

When the time came to port the pro- 
gram to another platform, a fellow devel- 
oper introduced me to RogueWave’s 
Tools.h++ foundation-class library. Sur- 
prisingly, it only took me three months to 
write the new version, which was only 
6000 lines long. Furthermore, the run-time 
speed of the app increased by more than 
an order of magnitude. 

This project made me a believer in good 
foundation-class libraries. Luckily, C++ pro- 
grammers have a variety of options, in- 
cluding STL, MFC, Booch, and RogueWave. 
In this article, I'll examine RogueWave’s 
Tools.h++, the cornerstone for all of my 
C++ work since that first successful project. 





RogueWave Tools.h++ Overview 
RogueWave’s Tools.h++ is a C++ class li- 
brary consisting of more than 100 C++ class- 
es, including those for time, dates, strings, 
linked lists, and other fundamental struc- 
tures. Other classes support virtual streams, 
string and character manipulation, file man- 
agement, regular expressions, tokenizers, 
virtual-page and buffered-page heaps, 
buffered-disk page heaps, timers, bench- 
marks, templates, bit vectors, cache man- 
agers, error handling, iterators, and more. 
The classes can be run as a DLL, allowing 
smaller executables and code sharing. 


Perry is a senior systems analyst for Arco 
Alaska and can be contacted at laspws@ 
ddal.arco.com. 
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Tools.h++ also includes a complete set 
of Smalltalk-like collection classes. Class 
Set, for instance, can be used to collect a 
group of screen windows that will need 
to be refreshed, eliminating redundant re- 
freshes. All classes support persistence, al- 
lowing objects to be saved to disk and re- 
stored later. Multiple pointers to the same 
object can also be restored. All classes are 
extensible so that you can create your own 
custom classes. 

The class library is compatible with most 
compilers and platforms, including Win- 
dows 3.x, Windows 95, Windows NT, MS- 
DOS, OS/2, Macintosh, Sun/SunOS, So- 
laris, IBM RS/6000/AIX, Silicon Graphics 
Iris/IRIX, HP/HP-UX, DG/DG/UX, UNIX 
System V, and even Linux. 


String Support 

String manipulation is an area where class 
libraries can shine, and RogueWave’s RWC- 
String class family is no exception. In ad- 
dition to the expected behaviors for strings 
(dynamic resizing, concatenation opera- 
tors, and so on), RWCString is multithread 
safe and supports multibyte character sets. 
It uses “copy on write” methods during 
copy construction for higher efficiency. 
“Copy on write” maintains reference 
counts to a single instance until copying 
is forced by a change to one of the ref- 
erenced instances. 

RWCString is typically one of the first 
classes new Tools.h++ users become fa- 
miliar with. In Listing One (listings begin 
on page 110), for example, Operator() 
has been overloaded to accept a regular- 
expression argument. The operator returns 
a reference to a substring (RWCSubString, 
cousin of RWCString) whose extent is the 
segment “34.5”. The assignment operator 


Examining RogueWave's 
Tools.h++ 


A class library for C++ programmers 


“=” is used to replace segment “34.5” with 
segment “184.9”. This syntax is elegant and 
cleverly designed. 

Note that in Listing Two, RWCTokenizer 
does not alter the string being tokenized. 
This behavior is entirely different from the 
standard strtok, which deposits NULLs be- 
tween every token in the tokenized string. 
Note also that RWCStrings are aware of 
streambuf and virtual stream I/O. Rogue- 
Wave gives all of its foundation classes 
this ability. RWWString, the multibyte ana- 
log of RWCString, contains much of the 
functionality of RWCString, but under- 
stands wchar_t (wide char*) character 
units. 


Date/Time Handling 

If you have ever written (or maintained) 
time/date functions based upon time.h, 
you will appreciate Tools.h++’s time and 
date functionality. Classes such as RW- 
Date and RWTime let you program at 
the level of a Visual Basic programmer 
for such standard concepts as date and 
time. Listing Three illustrates how you 
can use these two classes. As Listing 
Four shows, RogueWave has also gone 
a long way toward supporting interna- 
tionalization. 

The only thing I’ve struggled with con- 
ceming RWTime is “4294967295,” the largest 
unsigned /ong. One of RWTime’s private 
members is the number of seconds since 
1/1/1901 UTC. Given that “02/05/2037 
21:18:15” is exactly 4,294,967,295 seconds 
from 1/1/1901, you have discovered an up- 
per time bound that you should be aware 
of if you need dates past 2037. There are 
many obvious workarounds, but I nonethe- 
less forgot about it— and users discovered 
it for me. 
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(continued from page 80) 

Template Classes 

Templates are parametrized collection 
classes, where the parameter is the type 
of the object being collected. Tools.h++ 
templates come in three flavors: intrusive 
lists, value-based collections, and pointer- 
based collections. Most of my recent de- 
velopment work has been with the point- 
er and value template classes. The stricter 
class typing inherent in template-based 
programming offers significant advan- 
tages over the older polymorphic- 
inheritance approaches. Templates greatly 
simplify complex data-structure manip- 
ulation. 

In general, value-based collections of- 
fer easier syntax (less pointer manipula- 
tion and manual free-store destruction) at 
the expense of decreased performance 
during insertions and deletions. The per- 
formance issue is related to the fact that 
value-based collections make copies of 
inserted items rather than simply refer- 
encing the pointer. 

I typically use value-based templates 
on small data structures of fairly constant 
size, “template-ready” classes from Rogue- 
Wave (RWCString or RWDate, for in- 
stance), or built-in types like floats or ints. 
When the data-structure complexity war- 
rants, or when the collection is frequent- 
ly updated through resizing or insertion, 
I generally pick a pointer-based template. 

Consider the data structure in Listing 
Five, which could represent a point on 
an X/Y curve and a textual description 
of the point. In order to collect this XY- 
Point structure in a Tools.h++ template, 
you must extend the data structure so 
that the semantics of the structure can 
be supported by the template. Clearly, 
these XYPoints should be stored in a 
sorted collection. The sort order should 
be determined by the xDate member. 
We must also know when two items are 
“equal.” In addition, copy construction, 
default construction, and assignment se- 
mantics should be defined; see Listing 
Six. The class XYPoint is now ready to 
be used with nearly any of the Tools.h++ 
pointer or value templates. In short, the 
templates features in Table 1 are auto- 
matically available when you use 
Tools.h++ templates. Listing Seven illus- 
trates both pointer- and value-sorted vec- 
tor template usage. 





Table 1: Tools.b++ template features. 
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All expected behavior for collections 
with the exception of object persistence 
is well covered by Tools.h++ templates. 
Templates in both the pointer and value 
variety include hash dictionaries, sorted 
vectors, ordered vectors, singly and dou- 
bly linked lists, hash sets (uniqueness en- 
forced), stacks, and queues. For those few 
compilers that do not yet support tem- 
plates or support them incompletely, 
Tools.h++ provides “generic” collection 


All expected 
behavior for 
collections with the 
exception of object 
persistence is well 
covered by Tools.h 
templates 





classes, similar to templates but less ef- 
ficient. These use some of the macro- 
based parametrized types described by 
Stroustrup. Few users will need these 
classes, but they may come in handy for 
the occasional compiler incompatibility 
problems that may come up during 
RogueWave installation. Gnu’s g++ has 
had some historical compatibility prob- 
lems with Tools.h++, so future releases 
of g++ may require the generic pseudo- 
templates. 


Adding Persistence 

Persistence is not built into the Tools.h++ 
templates, but RogueWave makes it easy 
to add object persistence by providing 
the RWvistream and RWvostream abstract 
base classes. These classes capitalize on 
the considerable strengths of the iostream 
model, but extend the functionality for 
arbitrary binary data and abstraction of 
byte sources and sinks. Tools.h++ pro- 
vides its own instantiable ASCII and bi- 
nary veneer over the streambuf class 
(RWplio/stream and RWbfio/stream, re- 
spectively). 


The beauty of virtual streams is the 
power that the generalization of data 
sources and sinks implies. When you send 
a class to a RWvostream, you are effec- 
tively sending it without concern for its 
storage format within the stream pipeline. 
This opens up all sorts of possibilities, 
such as using object persistence over net- 
work protocols like Berkeley sockets. You 
could write your object to a socket-based 
child of RWvostream, whereupon it could 
be received and read across the network 
by another socket-based child of RW- 
vistream. The implementation of the 
streaming operators to accomplish this be- 
havior is invariant across the choice of 
storage media. In other words, the same 
streaming functions can be used to store 
a class onto a network or an ASCII file. 
I’ve implemented such a scheme using 
Tools.h++’s RWbistream and RWbostream 
by adding virtual stream capabilities to a 
class of my own design. Then, I con- 
structed bistreams and bostreams on ei- 
ther end of an interprocess pipeline. I 
could then simply send the binary data as 
a class through the pipeline, whereupon 
it could be caught at the other end of the 
pipeline in exactly the state we had sent 
it. The result is elegant: Instead of send- 
ing a stream of bytes that must be reparsed 
on the other end, we send an entire ob- 
ject capable of reconstructing itself on the 
other side. The reconstructed object re- 
tains all of its original methods and prop- 
erties. 

In another recent engineering project, 
we discovered that an application of ours 
had become I/O bound. This program 
performed a series of material balance cal- 
culations on 600 multiwell patterns for the 
Kuparuk River Unit, the second largest oil 
field in the United States. It was too time 
consuming for the engineers to request 
the data from a relational database be- 
cause the data required for the material- 
balance calculations was extremely hi- 
erarchical. We decided, therefore, to 
implement a persistent RogueWave class 
capable of being written to and read from 
a RogueWave virtual stream. This class 
encapsulated the entire time-valued be- 
havior of a material-balance pattern, in- 
cluding the cumulative fluid amounts, 
reservoir-volume conversion factors, and 
initial properties of the pattern. The Ora- 
cle access speed per pattern was about 
30 seconds. With Tools.h++ virtual streams, 
we were able to cut access time to a frac- 
tion of a second. The Oracle data was pro- 
cessed at night in a huge batch process 
into the RogueWave object database. In 
the morning, the engineers were able to 
rapidly flip through the patterns and make 
decisions at a much faster rate. 

Listing Eight extends the XYPoint class 
to be “virtual-stream aware.” Since RW- 
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Date and RWCString are already virtual- 

stream aware, this task becomes trivial. 
These functions store the individual class 

you are collecting, but what about the 

collection itself? How do you implement 

persistence for a Tools.h++ template col- 


lection? For simple vectors, you must 


store only the integer number of elements 
followed by the individual members of 
the collection. This is not a preferred 
method due to the loss of objectmor- 
phology. However, if you purchase the 
source code from RogueWave, you can 
build children of the template classes 
which contain some of the persistence 
methods of the Smalltalk collectable class- 
es. I’ve implemented a child of RW7Ptr- 
Sorted Vector with some basic persistence 
capabilities without much trouble. 


Smalltalk-like Collection Classes 

If you use polymorphic inheritance trees 
in your class design, you will not be dis- 
appointed with RogueWave’s implemen- 
tation of its Smalltalk-80-like Collection 
Classes. Any object of this variety must ul- 
timately be derived from the RWCollectable 
abstract base class, the root of the inheri- 
tance tree. Although the trend seems to be 
moving away from this variety of class de- 


sign and toward templates, this approach 
has distinct advantages. The programming 
interface is a bit cleaner. There is an aes- 
thetic “goodness” in the fact that inheri- 
tance trees reuse object code rather than 
source code (as templates do). Tools.h++ 
also provides elegant, more-complete per- 


sistence methods for all children of RW- 


Collectable. The persistence methods alone 
make RWCollectable worthwhile for pro- 
jects that store and retrieve objects from 
files other than traditional databases. 


The methods for making a class RW- 


Collectable are similar to those for mak- 
ing it compatible with Tools.h++ tem- 
plates, but more extensive. The usual 
methods for equality, comparison, con- 
struction, and destruction must be de- 
fined. RWCollectable classes must addi- 
tionally redefine virtual persistence 
functions restoreGuts and saveGuts. These 
functions have been overloaded for both 
RWFile (a file I/O veneer class) and 
RWo/io/stream classes. An isA() function 
must be defined to return the type of an 
RWCollectable child. This allows you to 
identify object types during ambiguous 
moments such as construction of col- 
lectibles whose type is unknown until run 
time. The weak typing of such class de- 
sign can lead to the usual casting prob- 
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lems of all inheritance trees, but being 
able to store several types of RWCollectable 
classes within common containers such 
as RWSortedVector and RWBTreeDictionary 
is compensation enough. 


Object-Database Management 

The strong suit of the Smalltalk Tools.h++ 
classes is their advanced persistence mech- 
anisms. However, a database must know 
how to organize multiple objects on a disk 
all at once and be able to retrieve them 
rapidly. RWFileManager, child of RWFile, 
performs such a function by maintaining 
a linked list of free-space blocks within a 
disk file. Requests can be made to RW- 
FileManager for just enough space to store 
a given class instance. RWCollectable class- 
es can return the space required to store 
themselves with member function binary- 
StoreSize(). RWBTreeOnDisk maintains a 
B-tree on the disk file. The disk-based 
B-tree is used in conjunction with RW- 
FileManager to associate a name (const 
char*) with each object stored with RW- 
FileManager. 

The name can be used later to retrieve 
the object from the disk file using the high- 
speed disk B-Tree. I’ve used this technique 
when storing large amounts (up to 50-MB 
files) of X/Y curve objects. These file- 
management classes are robust and ex- 
tremely fast and provide an alternative stor- 
age mechanism for data that does not fit 
well within the relational paradigm. (For 
details on an application that implements 
this feature, see my article “Simplifying C++ 
GUI Development,” DDj, September 1995.) 

In Listing Nine, which illustrates how 
to use the Tools.h++ object-database man- 
agement facilities, my address is stored on 
the disk file with the key “Perry.” As List- 
ing Ten shows, retrieving the address is 
straightforward. 


Conclusion 

The parts of the Tools.h++ library I’ve ex- 
amined in this article barely scratch the 
surface of what RogueWave offers. The li- 
brary also provides database wrappers, 
graphics libraries, linear-algebra support, 
a Motif wrapper, and even its own version 
of the Booch Components. In short, 
RogueWave has a tool for just about any 
standard programming task. 
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(Listings begin on page 110.) 
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orty years ago, it took a group of ex- 
perts 17 staff years to write the first 
Fortran compiler. Today, a single pro- 
grammer with less knowledge can do 
essentially the same thing in a matter of 
weeks. What makes this possible are ad- 
vances in both computer science and 
software-development tools. In particu- 
lar, tools such as lex and yacc become 
powerful allies in the hands of pro- 
grammers who know how to use them. 
For instance, I’ve used lex and yacc for 
everything from converting queries to 
SQL syntax, to verifying that examples 
of server command files were consistent 
with command syntax. 

In this article, I’ll first examine lex and 
yacc, focusing on the MKS Lex & Yacc 
Toolkit for DOS, OS/2, and Windows NT. 
MKS Lex builds a C/C++ or Turbo Pas- 
cal lexical analyzer that takes a stream 
of input and breaks it into tokens ac- 
cording to specific rules. MKS Yacc, on 
the other hand, builds a C/C++ or Tur- 
bo Pascal parser that takes a stream of 
tokens, matching them against a speci- 
fied grammar. Uf you have a UNIX sys- 
tem, lex and yacc may already be in- 
stalled. Free versions, such as flex and 
bison, will compile in almost any sys- 
tem.) To illustrate the power of these 
tools, I’ll then describe how I used them 


to build a keyword-query compiler for 


a CD-ROM database. 


Lex and Yace Backgrounder 

Yacc generates a parser, yyparse(), that 
checks whether or not different parts of 
the input (ike numbers, variable names, 
and operators) are in the correct order. It 
then processes those parts. Usually the or- 
der of processing is different from the or- 
der of input. 


Ian is a software developer and systems 
analyst. He can be reached at Active- 
Systems Inc., 11 Holland Ave., Suite 700, 
Ottawa, ON, Canada K1Y 4817. 
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Lex and Yacc 


lan E. Gorman 


Lex generates a lexer, yylex(), that splits 
the input into substrings, which it then 
classifies for the parser. The lexer can also 
do some preliminary processing. yylex() 
always returns a type code (called a “to- 
ken”). For some substrings, yylex() may 
also put a value (called an “attribute”) in 
the global variable yylval. 

Listings One and Two (listings begin on 
page 113), extracted from the MKS Lex 
and Yacc documentation, build an inter- 
preter with lex and yacc. The interpreter 
is a simple, four-function calculator, with 
up to 26 variables (A to Z) for temporary 
storage. Writing such a calculator in C is 
a fairly big job; with lex and yacc, you 
need only the code in the listings. 

The lex code (Listing One) is just a list 
of regular expressions, with their associ- 
ated code segments. Each code segment 
executes when a substring of the input 
matches the corresponding regular ex- 
pression. Lex puts the matching substring 
in the global variable yytext. Thus lines 8 
to 16 classify the single letters A to Z (and 
a to z) as VARIABLE, and produce a val- 
ue from 0 to 25, which the parser will use 
to identify the particular variable. Similar- 
ly, lines 18 to 21 classify an unbroken 
string of digits as INTEGER, and convert 
the string to an integer for use by the pars- 
er. In this way, input strings are classified 
and given some initial processing before 
any of the input goes to the parser. 

The yacc code (Listing Two) is a list of 
constructions (or recipes) for building new 
objects out of old ones. For example, lines 
26 to 34 show how the calculator program 
handles arithmetic expressions (like sum 
and difference). Any INTEGER coming in 
from the lexer is an expression (line 27). 
A VARIABLE identifies an array element in 
which to store the value of an expression 
(line 28). Expressions can be constructed 
from previously constructed expressions 
(lines 29 to 32). 

Objects from the lexer are normally 
identified in yacc code by character con- 


Compiler-construction techniques for 
the everyday programmer 


stants or uppercase names; objects con- 
structed by the parser are usually identi- 
fied by lowercase names. This makes it 
easier to read and understand the code. 
You attach code to each construction by 
placing the code in braces after the ob- 
jects that you use to build new objects. 
The value of the new object is represent- 
ed by $$ signs. The values of the old ob- 
jects are represented by $1, $2, and so on, 
from left to right. If the parser cannot im- 
mediately use the result, it goes on a stack 
(managed by code that yacc produces) 
until it is needed. The equation ad=3+ 4*c, 
for example, must be processed in reverse 
order of input, but you only have to write 
code for simple constructions: c (ine 28), 
4%*c (line 31), 3+expression (line 29), and 
a=expression (line 23). In the equation 
a=(3+ 4)*c, addition must be done first. 
Line 33 handles this case. After an open- 
ing parenthesis, the parser can accept only 
a complete expression followed by a clos- 
ing parenthesis. The parser stores five ob- 
jects eading parenthesis, first expression, 
plus, second expression, and trailing 
parenthesis) on a stack, then recognizes 
them as an expression (line 33), pulls them 
off the stack, and replaces them on the 
stack by one new expression. 

The two equations illustrate the labor- 
saving power of yacc. You do not have to 
figure out when and how to save inter- 
mediate results for an infinite variety of 
possible calculations. You do not even 
need to know how such things are done. 
You only need to find a simple way to 
build complex structures out of simple 
structures, and write your own code to 
process the simple structures. 


A Keyword-Query Compiler for a 
CD-ROM Database 

The CD-ROM databases I help build allow 
users to retrieve data by keyword search- 
es on one or more fields. To search for a 
record with either the word “harry” or the 
two words “tom” and “dick” in a single 


Dr. Dobb’s Journal, February 1996 










Learn how to develop and maintain nyour Very Large Database at: 


EXPERT SESSIONS ON: Th e 2nd Annual 


¢ VLDB Performance 
Design _ | i . i 


¢ Large Decision Support 
Case Studies 


¢ Techniques for Huge 
Data Warehouses 


* High Availability and 
Recovery 


¢ Parallel Databases: SMP. 
MPP 


¢ Data Mining and 
Business Intelligence 


VOB Upsizing Tips fo April 29 : May 1, 1996 
racle, Informix,Sybase [se 


and DB2 ; Ch | C d ! 0 J IL 


Sponsored by: 





For information FAX to: (415) 905-2218 | 


Please send the 2nd Annual VLDB 
Summit catalog when available. 

Please register me for the 2nd Annual 
VLDB Summit in Chicago, IL on April 29 - May 1, 1996. 













Name 





“bavanady @ ellen? staven s6ivtions. adie 

_ } Company 

__: Address 

| City | State Zip 
Phone | Fax 

















DBS95 





Unleash your 
Pentium/Alpha! 


Microway's NDP Fortran & C|C++ are the 
only 32-bit compilers which take full ad- 
vantage of the Pentium and Alpha's dual 
numerics units. They run on DOS, LINUX, 
OS/2, NT and OS/F. To get RISC numeric 
performance from a Pentium or Alpha you 
need to schedule your code and use Su- 
ar aap optimizations. In his Jan. '95 Dr. 

obbs article, S. Fried describes how to get 
35 megaflops from a Pentium using NDP 
Fortran. The Alpha version of NDP Fortran 
hits 88 megaflops running on OS/F or NT 
systems or on DOS using Microway's new 
ISA add in card. Put our compilers or Pen- 
tium, 1860 and Alpha systems to work for 
you today. Call for white papers on Pen- 
tium, 1860, or Alpha Code Generation. 


(860/Pentium/Aloha 
SuperCompufers 


BX Series Pentium/AIpha/i860 Workstations - 
Microway's workstations and industrial PC's come 
configured with DOS, OS/2, UNIX, From....$2195 


Gigacube |hree tosix QuadPuters - Up to 24 
i860's for $50K! Computational Server runs NFS. 


Number Smasher~860 Upto 80 megaflops, 
does 1024 FFT injust .9 ms, From...............$2995 


Quad Puter’860 Four 40 MHz 1860's plus shared 
memory equals 320 megaflops 


ArrayPRO/XP™ - 100/200 megaflops, 400 MB/Sec 
memory, 80 and 33 MB/Sec DSP Interfaces.... $8995 


Number Smasher®Alpha 100+ megaflops - this 


ISA Superscalar add incard runs on DOS or UNIX. 


It uses T8 links for parallel processing. From $5995 


\\/ BD) man Oxo) 00) 0)/(=)65 


Microway's family of 32-bit compilers run on 
DOS, OS/2, NT, UNIX, and OS/F generating 
code for the Intel 386, 486, Pentium, 1860 and 
DEC Alpha. 

NDP Fortran™ is a full F77 with complete 
VMS, F66, DOD, and MS extensions. 

NDP C|C++™ runs in K&R, ANSI and C++ 
modes and generates the highest quality 
numeric code of any 32-bit C compiler. 


NDP Pascal” is a full ISO Level 0 translator. 


DOS releases include VCPI, DPMI, NDPLink, 
VM, NDPLib and GREX-Microway's bit mapped 
graphics library. The 486/Pentium version adds 
486/Pentium code generation, Clearview, the 
MGxX vector graphics library, and DPMI DOS 
Box support for demand paging and GREX. 
BSC VEUSION FF osccdecssisntasscosectosscstseesees: $695 
Pentium/486 Version 4.5............ccceeee $995 
OS/2 releases use IBM Tools, take advantage 
of the IBM WorkFrame and include MGX 





DON cep oie souicabeiuale oirge cs ead sadoneaei tana $595 
POE ONION secu ctasseteeaease nace races ene et $895 
Alpha NDP compilers start at... ee $795 


Call for UNIX, OSF and NT pricing. 
NDP Fortran 90 extensions to NDP Fortran. $295 


Microway 


Research Pork, Kingston, MA 02364 USA 
(508) 746-7341 FAX (508) 746-4678 
Call for Germany, India, Indonesia, Israel, 
Japan, Poland, Russia and U.K. 





CIRCLE NO. 92 ON READER SERVICE CARD 





(continued from page 86) 

field, the user would enter a keyword list 
tom dick, harry. Words in a list separated 
by spaces must all appear in the field. Lists 
separated by commas are alternatives; a 
record will be selected if a field satisfies 
any one of the lists. Thus spaces are equiv- 
alent to a logical AND, and commas are 
equivalent to a logical OR. 

I used an off-the-shelf search engine 
that requires the query to be like Exam- 
ple 1. While this looks like SQL, the op- 
erators <, <=, =, >=, and > do not mean 
what they would in a relational database. 
They are containment operators instead 
of comparison operators. For example, 
FIELD 1 = ‘joe’ indicates that FIELD1 con- 
tains joe’ (possibly with other words), not 
that FIELD1 has the value ‘joe’ Similarly, 
FIELD1 < ‘'joe' indicates that FIELD1 con- 
tains some word less than ‘oe’ A field 
with the value ‘xerxes jack' would satisfy 
this condition. 

I didn’t want to expose nontechnical 
users to the engine query language, par- 
ticularly when it looked like a language 
(SQL for relational databases) with differ- 
ent operators. Consequently, I wrote a 
parser to convert user expressions to ex- 
pressions that the query engine would ac- 
cept; see Example 2. 


Other Design Issues 
The retrieval engine was designed to work 
with one database, and it used global vari- 
ables. I moved the engine C code into a 
C++ database class, changing the global 
variables to private variables in that class. 
This allowed me to have several open 
databases instead of one. I could use 
much of our existing C interface code by 
changing the function declarations, mak- 
ing the functions public members in the 
database class. 

The compiler allocates temporary stor- 
age on the heap, and any yacc-based 


compiler will discard some of the corre- | 


sponding pointers when it detects an er- 
ror. I therefore entered each of these point- 
ers in a list-manager class when I allocated 
data in the compiler. Deleting the list man- 
ager after each compiler run guarantees 
that all memory is freed. 





Bec raenaaarg 
ee a 


ins 


1 query by off-the 


engine accepts. 


Since the rest of the package was writ- 
ten in C++, I preferred to write the parser 
in C++. This is easy to do with MKS Yacc. 

When searching on multiple fields, the 
field expressions are connected by AND or 
OR, but in left-to-right precedence (or from 
top of screen to bottom) instead of the usu- 
al precedence of AND over OR. Conse- 
quently, I used yacc only for the individu- 
al field expressions, and used a simple C 
function to put the expressions together. 

I did not use lex because some of our 
applications defined keywords different- 
ly in each database. For example, one 
database might allow hyphenated words, 
but another in the same application might 
not. Lex requires you to specify the char- 
acters that can make up a keyword when 
you generate the compiler, not when you 
run it. This project had only a few differ- 
ent tokens (see Listing Three, lines 17 to 
22), so it was not hard to write the lexer 
in C++ instead of lex. 


Writing the Compiler 

I wrote the compiler in stages. I simulta- 
neously built a lexer and yacc grammar 
with no C++ code. The grammar and the 
lexer are interdependent. The lexer will 
not compile without a definition file that 
yacc produces from the grammar. The 
parser will not run without input from the 
lexer. However, you can do much of the 
testing before putting C++ code in the 
parser, because the C++ code is only used 
to produce the parser output. 

Listing Three is the code for a working 
parser that reads and parses input, and 
produces error messages for invalid input. 
In short, it does everything but produce 
the output. If you have designed a new 
language, like my keyword lists, you can 
change the grammar until you are satis- 
fied with the language. One of the great 
advantages of yacc is that you can do this 
kind of testing up front, before putting a 
lot of work into C/C++ code. 

The parser gets input (lines 17 to 22 of 
Listing Three) from the lexer. Starting from 
the bottom of Listing Three, the parser 
makes ever larger units out of input to- 
kens, until all input has been combined 
into one unit, which is the complete 
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search expression for one field. For ex- 
ample, you can follow a character string 
(CHARSTRING) up through lines 98-99, 
66-67, 57-59, and 42-43 until it be- 
comes part of the complete field expres- 
sion in lines 31-32. 

After you have a working parser, you 
can add code. Listing Four is some of the 
code that illustrates how the parser works. 
The variable scan is a pointer to an ob- 
ject of type Parseltem_t, created by the 
lexer. The object holds a string scan->Val- 
ue(), and you can append another string 
to that string with the member function 
scan->ConCait ). 

When a CHARSTRING comes in (lines 
55-70), and the field is a character field, 
the corresponding string value is quoted; 
if the field is numeric, it is not. Then the 
string is saved (by saving the pointer $$) 
as the value for the new token value. This 
particular section illustrates how the yacc 
grammar is influenced by the code you in- 
tend to write — if I had not wanted to pro- 
cess strings upon arrival from the lexer, I 
could have left this section out and replaced 
all occurrences of value with CHARSTRING. 

If the CHARSTRING lacks a preceding 
operator code, it will be concatenated with 
the fieldname and the =’ operator (lines 
29-37). If the CHARSTRING follows an 
operator (<, <=, >=, >), then it will be con- 
catenated with a fieldname and that op- 
erator (lines 29 and 40-50). Both cases 
produce a simplecondition. 

A compoundcondition (line 4) can be 
a simplecondition (ines 7-9). A com- 
poundcondition followed directly by a 
simplecondition will be ANDed with that 
simplecondition (ines 11-17). A com- 
poundcondition followed by a comma and 
then a simplecondition will be ORed with 
that simplecondition (lines 19-20). 

After the user keyword lists are con- 
verted to search expressions for each field, 
they are put together in an SQL command 
for the search engine. Since the expres- 
sions are concatenated very simply, this 
was done with a C++ program (Listing 
Seven) that called a setup program (List- 
ing Five) for each field. 


Conclusion 
The secret to using lex and yacc ina 
production environment is to pick prob- 
lems commensurate with your ability to 
use the tools, and to increase your abil- 
ity with practice. While the CD-ROM pro- 
ject I’ve described here may be trivial to 
a computer-science student, yacc saved 
us at least a week in development time. 
I found yacc handy when we changed 
the structure of our keyword language. 
Testing a change was a matter of a few 
minutes when we could change our yacc 
source, instead of several days if we had 
been writing in C or C++. 
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Lex and yacc are generally useful even 
when you are not in the compiler busi- 
ness. I have used lex and yacc to verify 
the syntax of languages that I was de- 
scribing in developer’s guides for a UNIX 
text-management server and a Windows 
text-search client. This alerted me imme- 
diately to changes that occurred in the lan- 
guage definitions as the design of the serv- 
er and client evolved. I’ve also used lex 
and yacc to produce SGML output from 
proprietary text markup. We eventually 
switched to other tools, but we used a 
modified version of the lex program as a 
preprocessor. In another project, I used 
lex and awk to extract English literals from 
Visual Basic programs and replace them 
with French literals. Finally, ’ve used lex 


AAA TT A TL RT TR RN RNR 


and MKS Toolkit (UNIX utilities for DOS) 
to automate corrections to 18,000 pages 
of scanned documents, preventing a de- 
lay of several weeks in delivery. 
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STANDARD WEB API 


° ° 
Listing One 
#include "protocol_lib.h" 
/* X-way to define resources and parse the cmdline args */ 


/* WebRouser 2.6-b2 gives the embedded window information through these args */ 
typedef struct{ 


int win; 

int pixmap; 

int pixmap_width; 
int pixmap_height; 
char *datafile; 


} ApplicationData, *ApplicationDataPtr; 

static XtResource myResources[] = { 
{"win", "Win", XtRInt, sizeof(int), 
XtOffset (ApplicationDataPtr, win), XtRImmediate, 9}, 
{"pixmap", "Pixmap", XtRInt, sizeof(int), 
XtOffset (ApplicationDataPtr, pixmap), XtRImmediate, 0}, 
{"pixmap_width", "Pixmap_width", XtRInt, sizeof(int), 
XtOffset (ApplicationDataPtr, pixmap_width), XtRImmediate, 400}, 
{"pixmap_height", "Pixmap_height", XtRInt, sizeof(int), 
XtOffset(ApplicationDataPtr, pixmap_height), XtRImmediate, 400}, 
{"datafile", "Datafile", XtRString, sizeof(char*), 
XtOffset (ApplicationDataPtr, datafile), XtRImmediate, NULL}, 


le 

static XrmOptionDescRec myOptions[] = { 
{"-win", "*win", XrmoptionSepArg, 9}, 
{"-pixmap", "*pixmap", XrmoptionSepArg, @}, 
{"-pixmap_width", "*pixmap_width", XrmoptionSepArg, @}, 
{"-pixmap_height", "*pixmap_height", XrmoptionSepArg, @}, 
{"-datafile", "*datafile", XrmoptionSepArg, NULL}, 

} . 


ApplicationData myAppData; 


void myDraw() 
{ 


/* do your drawing... */ 


/* if you draw into your own drawables (myPixmap in this case) */ 
if (myAppData.win) { 
/* copy from myPixmap to the "shared" pixmap */ 
XCopyArea(display, myPixmap, myAppData.pixmap, myGC, @, @, WIN_WIDTH, 
WIN_HEIGHT, @, @); 
/* tell WebRouser to update the drawing window */ 


send_client_msg(XtNrefreshNotify, display, myAppData.win) ; 
} 


void myQuit () 


af 
/* tell WebRouser you are exiting... */ 
if (myAppData.win) 
send_client_msg(XtNpanelExitNotify, display, myAppData.win) ; 
/* Motif way of exiting */ 
XtCloseDisplay(XtDisplay(any widget) ); 
exit (1); 
} 
main() 
{ 
Widget app_shell; 
/* XtInitialize does XOpenDisplay, as well as creates a toplevel widget */ 
app_shell = XtInitialize("wt", "Wt", myOptions, XtNumber(myOptions) , 
&arge, argv); 
/* This func fill up myAppData with user specified values/default values */ 
/* We get the embedded window's info this way */ 
XtGetApplicationResources(app_shell, &myAppData, myResources, 
XtNumber (myResources), NULL, @); 
/* if we have an external window to display the image... */ 
if (myAppData.win) { 
XtAddEventHandler (app_shell ,NoEventMask,True,handle_client_msg,NULL) ; 
register_client(app_shell, display) ; 
/* register the func to be called when WebRouser exits */ 
register_client_msg_callback(XtNexitNotify, myQuit) ; 
/* tell WebRouser you have started fine */ 
send_client_msg(XtNpanelStartNotify, display, myAppData.win) ; 
} 
XtMainLoop(); /* Motif's event loop */ 
} 


/* End of program listing */ 


KERMIT 


Listing One 


STATIC int KSendPacketFromCache (KERMIT_PRIVATE *pK,long sequence,int addToList) 
{ 
- int slot = sequence & 63; 
long prev, next; 


if ((pK->exchange[slot] .myPacket.type == @) 
|| (pK->exchange[slot] .myPacket.data == NULL) ) 
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return kOK; 


prev = pK->exchange[slot].previousPacket; /* Unlink from list */ 
next = pK->exchange [slot] .nextPacket; 


if 
if 
if 
pK- 
pK- 
if 


} 
pK- 
pK- 


ret 


} 
STATIC 
{ 
int 
int 
int 
int 
C7 


} 
Sts 
if 
if 


err 
do 


((pK->lastPacket & 63) == slot) pK->lastPacket = prev; 

(prev >= @) pK->exchange[prev & 63].nextPacket = next; 

(next >= 0) pK->exchange[next & 63].previousPacket = prev; 

>exchange [slot] .nextPacket = -1; 

>exchange[slot] .previousPacket = addToList ? pK->lastPacket : -1; 

(addToList) { 

if (pK->lastPacket >= @) /* Add to end of list */ 
pK->exchange[pK->lastPacket & 63].nextPacket = 

pK->exchange [slot] . sequence; 
pK->lastPacket = pK->exchange[slot] .sequence; 


>exchange[slot].tries++; /* Count number of sends */ 
>exchange[slot].sendTime = SerialTime (pK->initTime) ; 
/* Stamp time of send */ 
urn StsWarn (KSendPacket (pK, slot, pK->exchange[slot] .myPacket.type, 
/* Send it */ 
pK->exchange [slot] .myPacket.data, 
pK->exchange[slot] .myPacket.length) ) ; 


int KSendPacketReliable(KERMIT_PRIVATE *pK, BYTE type, 
const BYTE *pSendData, unsigned long sendDataLength, 
unsigned long rawDataLength) 


blocked = FALSE; 
err; 
slot = pK->sequence & 63; 
timeout = pK->my.timeout; 
* Put packet into cache */ 
EXCHANGE *pThisExchange = &(pK->exchange[slot]); 
if (pThisExchange->myPacket.data == NULL) { 
if (pK->minCache < pK->minUsed) { 
SwapSlots (pK->minCache, slot); 
/* Move free exchange to end of window */ 
pK->minCachet++; 
pThisExchange->yourPacket.type = 9; 
} else return StsWarn (kFail); /* Internal consistency failure */ 
} 
if (pSendData == pK->spareExchange.myPacket.data) { 
/* In the reserved slot ? */ 
BYTE *pTmp = pThisExchange->myPacket.data; /* Just swap it in */ 
pThisExchange->myPacket.data = pK->spareExchange.myPacket.data; 
pK->spareExchange.myPacket.data = pTmp; 
} else /* copy it */ 
memcpy (pThisExchange->myPacket.data, pSendData, sendDataLength) ; 
if (pK->sequence > pK->maxUsed) pK->maxUsed = pK->sequence; 
/* Update end of window */ 
pThisExchange->sequence = pK->sequence; 

/* Finish initializing this exchange */ 
pThisExchange->myPacket. length = sendDataLength; 
pThisExchange->myPacket.type = type; 
pThisExchange->rawLength = rawDataLength; 
pThisExchange->tries = 9; 
pK->txPacket.data = pK->spareExchange.myPacket.data; 
pK->txPacket. length = Q; 


Ret (KSendPacketFromCache (pK, pK->sequence, TRUE)); /* Send packet */ 
(pK->minUsed <= pK->minCache) blocked = 1; /* Are we blocked? */ 
(pK->maxUsed - pK->minUsed + 1 >= pK->currentWindowSize) 
/* How blocked are we? */ 
blocked = (pK->maxUsed - pK->minUsed + 1) - pK->currentWindowSize + 1; 
= KReceivePacketCache (pK, @); /* Get a packet if one's ready */ 
{ /* Until we're not blocked and there are no more packets pending */ 
switch (err) { 
case kBadPacket: /* Didn't get a packet */ 
case kTimeout: 
break; 
default: /* Unrecognized error, pass up to caller */ 
return StsWarn (err) ; 
case kOK: /* Got one! */ 
{ 
EXCHANGE *pThisExchange = &(pK->exchange[pK->rxPacketSequence & 63]); 
switch (pK->rxPacket.type) { 
case 'N': /* Got a NAK */ 
if (pThisExchange->myPacket.type != @) /* Resend packet */ 
StsRet (KSendPacketFromCache (pK, pK->rxPacketSequence, FALSE)) ; 
if ((pK->currentWindowSize > 1) |; (pK->maxUsed > pK->minUsed) ) 
break; /* Don't generate implicit ACKs for large windows */ 
pThisExchange = &(pK->exchange[(pK->rxPacketSequence - 1) & 63]); 
pThisExchange->yourPacket.type = 'Y'; 
case 'Y': /* Got an ACK */ 
if (pThisExchange->rawLength > @) { /* ACKed before?*/ 
if (pThisExchange->tries == 1) { /* Update round-trip stats */ 
long now = SerialTime (pK->initTime) ; 
long thisDelay = now - pThisExchange->sendTime; 
if (pK->roundTripSamplest++ == 0) { /* First sample? */ 
pK->roundTripDelay = thisDelay; 
pK->roundTripDelayVariance = @; 
} else { 
long oldAverage = pK->roundTripDelay; 
long diffSquared; 
if (pK->roundTripSamples > 30) /* Average first 30 */ 
pK->roundTripSamples = 30; 
/* Then decaying average */ 
pK->roundTripDelay += (thisDelay - pK->roundTripDelay) 
/ pK->roundTripSamples; 
diffSquared = (thisDelay - oldAverage) * 
(thisDelay - oldAverage) ; 
pK->roundTripDelayVariance += (diffSquared - 
pK->roundTripDelayVariance) / 
pK->roundTripSamples; 
pK->roundTripDelaySD = (pK->roundTripDelaySD + 
pK->roundTripDelayVariance / 
pK->roundTripDelaySD) / 2; 
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} 
} 
if (pK->sending) /* Update file progress on receipt of ACK */ 
pK->filePosition += pThisExchange->rawLength; 
pThisExchange->rawLength = @; /* Don't count packet again */ 


} 
{ 
long j, i = pThisExchange->previousPacket; 
while (i >= @) { /* Resend packets based on send order*/ 
j = pK->exchange[i & 63] .previousPacket; 
if (pK->exchange[i & 63].yourPacket.type != 'Y') 
StsRet (KSendPacketFromCache (pK, i, TRUE)); 
i= j; 
} 
} 


while ((pK->exchange[pK->minUsed & 63].yourPacket.type == ' 
&& (pK->exchange[pK->minUsed & 63].sequence == pK->minUsed) 
{ /* Free up slots that have been acknowledged */ 
long prev, next; 
prev = pK->exchange[pK->minUsed & 63].previousPacket; 
/* Unlink */ 
next = pK->exchange[pK->minUsed & 63] .nextPacket; 
if ((pK->lastPacket & 63) == (pK->minUsed & 63)) 
pK->lastPacket = prev; 
if (prev >= @) pK->exchange[prev & 63].nextPacket = next; 
if (next >= @) pK->exchange[next & 63].previousPacket = prev; 
pK->exchange [pK->minUsed & 63].previousPacket = -1; 
pK->exchange[pK->minUsed & 63].nextPacket = -1; 


tT) 
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pK->minUsed++; /* Mark this exchange as free */ 
if (blocked > @) blocked--; /* Reduce count to unblock window*/ 
} 
break; 
case 'E': /* Received error packet, terminate transfer */ 
return StsWarn (kFailed) ; 
default: /* Received unrecognized packet type, terminate */ 
return StsWarn (kFail); 
} 
} 
break; 
} 
{ /* Resend timed-out packets */ 
long = 
unsigned long now = SerialTime (pK->initTime) ; 
unsigned long packetTimeout = pK->roundTripDelay + 
3 * pK->roundTripDelaySD + 2 * SERIAL_TIME_SCALE; 
/* Avg + 3 standard deviations + 2 seconds */ 
long oldest = -1; 
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unsigned long oldestTime = ULONG_MAX; 
long firstOld = -1; 
for (i = pK->minUsed; i <= pK->maxUsed; i++) { 
if (pK->exchange[i & 63].yourPacket.type != 'Y') { 
if ((firstOld == -1) && (pK->exchange[i & 63].sendTime + 
packetTimeout < now) ) 
firstOld = i; /* Find first timed-out packet */ 
else if (pK->exchange[i & 63].sendTime < oldestTime) { 
/* Find oldest packet */ 
oldestTime = pK->exchange[i & 63].sendTime; 
oldest = i; 


} 
} 
if (firstOld != -1) /* Resend first timed-out packet */ 
StsRet (KSendPacketFromCache (pK, firstOld, FALSE)); 
if (oldestTime == ULONG_MAX) timeout = pK->my.timeout; 
else if (packetTimeout + oldestTime < now) /* Next oldest? */ 
timeout = 0; 
else /* Compute interval until next timeout */ 
timeout = (packetTimeout - (now - oldestTime)) / SERIAL_TIME_SCALE; 
if (timeout < 1) timeout = 1; /* Minimum is one second */ 
if (timeout > pK->my.timeout) timeout = pK->my.timeout; 
/* Max is negotiated value */ 
} 
err = KReceivePacketCache (pK, blocked ? timeout : 9); 
/* Try to receive a packet */ 
} while (blocked || (err == kOK)); 
if (pK->exchange[pK->sequence & 63].yourPacket.type && 
(pK->exchange[pK->sequence & 63].sequence == pK->sequence) ) 
pK->rxPacket = pK->exchange[pK->sequence & 63] .yourPacket; 
pK->sequencett; 
if (err == kTimeout) return kOK; 
if (err == kBadPacket) return kOK; 
return StsWarn (err); 


Listing One 


<FORM ACTION="http://yourmachine:urport/cgi-bin/testcgi.cgi" METHOD="POST"> 
<H1>Illustration Form</H1> 
<P ALIGN=JUSTIFY> 
This form is used as a illustration to the article on CGI. 
<HR> 
<INPUT TYPE="text" NAME="name" VALUE=""> 
Title<BR> 
<OL> 
<LI> <INPUT TYPE="radio" NAME="keyword" VALUE="author"> 
Author 
<LI> <INPUT TYPE="radio" NAME="keyword" VALUE="title" CHECKED> 
Title. 
</OL> 
<HR> 
<INPUT TYPE="submit" VALUE="Submit Form"> 
Submit Button<BR> 
<INPUT TYPE="reset" VALUE="Clear Values"> 
Reset Button. 


<P> 

</FORM> 

e e 
Listing Two 
HHHHHHHH RRR H HHH HEE HE RE HH HE HE HH HH EHH HHH RHE BH FF HE HH EE HH RE HH RH EHH BH FH 
## CGI-PARSE.PL ## 
## A library to read and parse the input available from forms as per the ## 
## CGI 1.1 specification. ## 


## This code is in the public domain for people to do whatever they wish to ## 
## with it. But, maintain this copyright notice and don't say you wrote it. ## 
## This work is distributed in the hope that its useful. But, the author is ## 
## not liable for any any incurred damages, directly or indirectly due to ## 
## the use or inability to use this software. t# 
HHHHHHHHRREHRE PPR RPR REAPER EERE E PERSE PERE ERE REP ERR ERPS RHR REE RR EHH HHH HH 
HHHHHHHHHHHHHREHREPEERERHRER RHR EE PERSE RHE HH HERE HHH HH HE RH RH HHH HH HH HHH HH HH HHH HH HH 
## CGIGetInput ## 
## This is a small function which decodes the forms input. It looks at the ## 
## REQUEST_METHOD environment variable to decide where to get the input from. ## 
## The user can invoke this subroutine thus : ## 
## &CGIGetInput (*cgi_in) ; ## 
## and the input is returned in an associative array called cgi_in, with the ## 
## key being the name of field and its value being the value of the field ## 
## as supplied by user. If the field does not have any input, the entry in ## 
## the associative array will be undefined. ## 
HHHHHHHHHHHRHRHEHEHERH PERERA RRERH AER RAE B HERS R SREP ERE ESRE REESE HHH HHH HH HSH HH 


sub CGIGetInput { 
local (*input) = @_; 
local (Sbuffer,@nv_pairs) ; 
if (SENV{'REQUEST_METHOD'} eq "GET") { 
Sbuffer = SENV{'QUERY_STRING'}; 
} 


elsif (SENV{'REQUEST_METHOD'} eq "POST") { 


(continued on page 94) 
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(continued from page 92) Listing Three 


read (STDIN, $buffer, SENV{'CONTENT_LENGTH'}) ; 


} HHHPHHHHHHREHRRHH HEE RRHHREH REE RE RE RRRRPHH PEEP H EH RE HHA RHE REE ER EH HEE HEE 
else { ## DEBUGCGI . PL ## 
return -1; ## This is a simple script which sets up a test environment for CGI script ## 
} ## to be executed and then traps the common errors. The PATH is set to the ## 
@nv_pairs = split (/\&/,$buffer) ; ## minimal set by most systems, for example. All error messages are trapped ## 
## and made available to the user. ## 
foreach $nvp (@..$#nv_pairs) { ## ## 
$nv_pairs[$nvp] =~ tr/+/ /; ## This code is in the public domain for people to do whatever they wish to ## 
($key, S$keyword) = split (/=/, $nv_pairs[Snvp], 2); ## with it. But, maintain this copyright notice and don't say you wrote it. ## 
Skey =~ s#%(..)#pack("c",hex($1) )#ge; ## This work is distributed in the hope that its useful. But, the author is ## 
Skeyword =~ s#%(..)#pack("c",hex($1))#ge; ## not liable for any any incurred damages, directly or indirectly due to ## 
Sinput{$key} .= '\®' if (defined (Sinput{Skey})); ## the use or inability to use this software. #i# 
$input {$key} .= $keyword; HHHHHHHHHHEHH HEAR RPE EHR E EHR EH RHR RARER RHEE HERR EE BREE ERE E REE E RSS BEE oH HS RS 
} 
return 1; Stmpdir = "/tmp/"; # The directory under which the error file will 
} # be created. 
require "cgi-parse.pl"; 
HHHHHHHRRR RHE RRA RR ARR RRE RHE RSE RSE RHEE RSH ER HERRERA EER SH RHEE ERS HHH REE HE %cgi_input = (); 
## &PrintHeader (type/URL, is_it_a_URL) ## &CGIGet Input (*cgi_input) ; 
## This function prints the default header. If a type is specified, that is ## 
## printed, else the default text/html is printed. If the second parameter is## Sscript = $cgi_input{'DebugCgi-ScriptName'}; 
## 1, then the Location header is printed instead of the text/html header. ## $method = $cgi_input{'DebugCgi-Method'}; 
## ## Scmdargs = $cgi_input {'DebugCgi-CmdArgs'}; 
## Example invocations : ## delete ($cgi_input {'DebugCgi-ScriptName'}) ; 
## &PrintHeader ("text/plain", @) ## delete ($cgi_input {'DebugCgi-Method'}) ; 
## &PrintHeader ("http://www.halcyon.com/hedlund/cgi-faq/",1)  ## delete ($cgi_input {'DebugCgi-CmdArgs'}) ; 
## &PrintHeader ("",@) ## 
HTH RG HHH HH HH HH i tH HH HH HH HH EH HE RBH SEB HH EB BH HHH FB HHH EH HHH HH HH HHH EH HH HH HH Sinp = ""; 
foreach Selem (keys %cgi_input) { 
sub PrintHeader f{ Scgi_input{Selem} = $cgi_input{$elem}; 
local (Stoprint, $url_p) = @_; Scgi_input{Selem} =~ s# #+#g; 
Scgi_input{Selem} =~ s#([*+A-Za-z@-9])#sprintf("%%%02x",ord($1))#ge; 
if ($toprint eq "") { Scgi_input{Selem} =~ s#%3d#=#g; 
print "Content-type: text/html\n\n"; Sinp .= "Selem=S$cgi_input {Selem}&"; 
} } 
elsif ($url_p) { # Encode the input in the form used by HTTP. 
print "Location: $toprint\n\n"; #Turn off the include path. The script must use its own @INC and environment. 
} if (! -e Sscript) { 
else { &PrintErrHeader ; 
print "Content-type: $toprint\n\n"; print "<B>Script <EM>$script</EM> does not exist</B><BR>"; 
} &PrintErrTrailer; 
} exit (2); 
13 } 
if (! -r Sscript && ! -x $script) { 
&PrintErrHeader ; 
print "<B>Script <EM>$script</EM> is not readable/executable by 
server</B><BR>"; 
&PrintErrTrailer; 
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exit (2); 
} 
#Set the request method. 
Serror_file = $tmpdir.$*T; 
SENV{'REQUEST_METHOD'} = $method; 
if ($method eq "GET") { 
SENV{'QUERY_STRING'} = Sinp; 
open (OUTPUT, "Sscript Scmdargs 2\>/tmp/errors |") || 
&cry ("unable to pipe script $! \n"); 


} 
elsif ($method eq "POST") { 
SENV('CONTENT_LENGTH'} = length($inp) ; 
open (OUTPUT, "echo \"$inp\" | Sscript Scmdargs 2>$error_file |") || 
&cry ("unable to pipe script $! \n"); 


} 

else { 
&PrintHeader; 
print "Unknown method: $method\n"; 
exit (3); 

} 

$_ = <OUTPUT>; 


if (!/*Content-type: / && !/*Location: /) { 
if (-s Serror_file) { 
open (ERRF, "< Serror_file") || &cry ("testcgi.cgi - 
Unable to open error file $!\n"); 
&PrintHeader ; 
print "<HTML><BODY>\n"; 
@errors = <ERRF); 
&PrintErrHeader ; 
print "<B>Script <EM>$script</EM> has an execution 
error !!!</B><BR><BR>"; 
print "@errors \n"; 
&PrintErrTrailer; 
unlink (Serror_file) ; 
exit (4); 
} 
&PrintErrHeader ; 
print "The script <EM>$script</EM> has an error :<BR><BR>"; 
print "It does not output the Content-type/Location header.<BR>"; 
print "Here's what it printed as the first line.\n"; 
print "<PRE>\n"; 
print; 
print "</PRE>\n"; 
&PrintErrTrailer; 
exit (3); 
} 
$format = m#*Content-type:[ \t]*text/html#; 
$_ = <OUTPUT>; 
if (1/*$/) { 
&PrintErrHeader ; 
print "The script <EM>$script</EM> has an error :<BR><BR>"; 
print "The second line it outputs must be a blank, instead I got <PRE>\n"; 
print; 
print "</PRE>"; 
&PrintErrTrailer; 
exit (3); 
} 
&PrintHeader; 
print "<HTML><BODY><H3>Script <I>$script</I> seems OK !</H3> \n"; 
print "<P ALIGN=Justify> Here is its output:<BR>\n"; 
print "<PRE>\n" if (!$format) ; 
print SENV{'PATH_INFO'},"\n"; 
while (<OUTPUT>) { 
print; 


print "</PRE>" if (!$format) ; 
print "</BODY></HTML>"; 
exit (0); 


sub cry { 
local ($message) = @_; 
&PrintHeader ; 
print "<HTML><BODY><H2>Debugegi Error !!</H2>"; 
print "DebugCGI encountered an error during execution. 


The error is: ", $message; 
print "\n<BODY><HTML>"; 
exit; 
} 
sub PrintErrHeader { 
&PrintHeader ; 
print "<HTML><BODY><H3>Script Error !!</H3>"; 
} 


sub PrintErrTrailer { 
print "</BODY></HTML>\n"; 


} 

e e 
Listing Four 
HHHHHHHHHHHHRHHHHHHHH HERR HH RER RRR RR ERR RR EHR R HH HHH H RRR HHH H HH HHH HH HEH HH RH HH RE 
## TESTCGI.PL ## 
## This is a script which sets up a test environment for the CGI script ## 


## to be executed and then traps the common errors. The PATH is set to the ## 
## minimal set by most systems, for example. All error messages are trapped ## 
## and made available to the user. Thus, he does not have to wonder why for ## 
## error cases. ## 
## This code is in the public domain for people to do whatever they wish to ## 
## with it. But, maintain this copyright notice and don't say you wrote it. ## 
## This work is distributed in the hope that its useful. But, author is not ## 
## liable for any any incurred damages, directly or indirectly due to use ## 


## or inability to use this software. ## 
HHBHHHHHEHH REAR REAR RRA RA RE RE RE ERE ERE HH EH RE RE REE EHH RAH RHE RR RAE RRR HH 


Stmpdir = "/tmp/"; # Directory under which the error file will be created. 
require "cgi-parse.pl"; 
sub Usage { 
print "Usage: testcgi [-f filename containing input] -m METHOD scriptname\n"; 
print " where METHOD is GET/POST\n"; 
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exit (0); 
} 
%egi_input = (); 
&CGIGetInput (*cgi_input) ; 
&PrintHeader; 


Sscript = $cgi_input{'TestCgi-ScriptName'}; 
$method = $cgi_input{'TestCgi-Method'}; 
delete ($cgi_input {'TestCgi-ScriptName'}) ; 
delete (S$cgi_input {'TestCgi-Method'}) ; 


$inp = wn. 
foreach $elem (keys %cgi_input) { 
$cgi_input{$elem} = $cgi_input{$elem}; 
Scgi_input{$elem} =~ s# #+#g; 
Scgi_input{$elem} =~ s#([*+A-Za-20-9]) #sprintf ("%%%#02x",ord ($1) )#ge; 
Scgi_input{$elem} =~ s#%3d#=#g; 
$inp .= "Selem=$cgi_input {$elem}&"; 
} 
# Encode the input in the form used by HTTP. 


#Turn off the include path. The script must use its own @INC and environment. 
@INC=() ; 
SENV{'PATH'} = "/bin:/usr/bin/:/etc:"; 


#Set the request method. 
Serror_file = $tmpdir.$*T; 
SENV{'REQUEST_METHOD'} = $method; 

if ($method eq "GET") { 

SENV{'QUERY_STRING'} = Sinp; 

open (OUTPUT, "$script 2\>/tmp/errors |") || die "unable to pipe script $! \n"; 


elsif (S$method eq "POST") { 
SENV{'CONTENT_LENGTH'} = length($inp) ; 
open (OUTPUT,"echo \"$inp\" | $script 2>$error_file |") {1 die 
"unable to pipe script $! \n"; 


} 


else { 
print "Unknown method: $method\n"; 
exit (3); 
} 
print "<HTML><BODY>\n"; 
$_ = <OUTPUT>; 
if (!/4Content-type: / && !/*Location: /) { 
if (-s Serror_file) { 
open (ERRF, "< Serror_file") |; die 
"testcgi.cgi - Unable to open error file $!\n"; 


print "<HTML><BODY>\n"; 
@errors = <ERRF); 
print "<H3>Script $script has an execution error !!!</H3>\n"; 


(continued on page 90) 
ZONA S Sone 


Includes “Drop In” Language Engines for dBASE, POSTSCRIPT, HYPERTALK, 
SMALLTALK-80, C++, C, PASCAL, VHDL, PROLOG, FORTRAN-90, 
COBOL-85, VISUAL BASIC, LEX, YACC, GW BASIC, RTF, SNA/LU, SGML, 
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CodeCheck 6.0 


SOURCE CODE MANAGER 
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cations, Measures of complexity, Silent error detection, Code maintainability, 

and Portability. 

CodeCheck Version 6.0 is a programmable tool for managing all C and C + + source 

code on a file or project basis. CodeCheck is input compatible with all variants of K&R, 

ANSIC and C++.CodeCheck is designed to solve all of your Portability, Maintain- 

ability, Complexity, Reusability, Quality Assurance, Style Analysis, Library/Class 

Management, Code Review, Software Metric, Standards Adherence, and 

Corporate Compliance Problems. 

= Compliance -CODECHECK allows your corporate coding and project 
specification standards to be completely automated for compliance 
validation. 


30 day Money back guarantee! Free AIR Shipping anywhere in the world! 
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(continued from page 95) JAVA 


print "@errors \n"; 
unlink (Serror_file) ; 


; . e e 
aaa Listing One 
print "<H3>Script $script has an error !!!</H3>\n"; 
print "It does not output the Content-type/Location header. \n"; // -- Declare this source to be a part of the CmdLnArg package. 
exit (3); package CmdLnArg; 
} 
Sformat = m#*Content-type:[ \t]*text/html#; // -- Make use of shipped package for Vector, String, StringBuffer classes 
$_ = <OUTPUT>; import java.util.*; 
if (!/*S/) { 
print "Your second line must be a blank\n"; public class ArgProcessor 
exit (3); 
} // -- Args as passed into application 
print "<H3>Script $script Seems OK</H3> \n"; String args[] = null; 
print "<P ALIGN=Justify> Here is its output \n"; 
print "<PRE>\n" if (!$format) ; // -- All arg types we will process. Must be derived from GenericArgType. 
while (<OUTPUT>) { Vector vArgs = new Vector(); 
print; 
} // -- Constructor. Hang on to the arguments for when we need to 
print "</PRE>" if (!$format) ; // -- process them later. 
print "</BODY></HTML>"; public ArgProcessor 
exit (); ( 
String args[] 
) 
e e e 
{ 
Listing Five this.args = args; 
} // -- end constructor 
<!-- <FORM ACTION="mailto:brat" METHOD="POST"> --> // -- Adds one argument type for when we process 
<FORM ACTION="http://yourmachine:urport/cgi-bin/testcgi.cgi" METHOD="POST"> public void add 
<H1>Test CGI Form</H1> 
<P ALIGN=JUSTIFY> GenericArgType arg 
This form is used as a front-end to testcgi. ) 
<HR> 7! 
<INPUT TYPE="text" NAME="TestCgi-ScriptName" VALUE=""> vArgs.addElement (arg) ; 
Script Name<BR> } // -- end add 
<INPUT TYPE="text" NAME="TestCgi-Method" VALUE="POST"> // -- Process the args that were passed into the application and store 
Method<BR> // -- the results back in the argument types passed into the add method 
<!-- Insert the form to be tested minus the FORM header and trailer --> public void process 
<!-- and the Submit and clear buttons --> 
<HR> ) 
<INPUT TYPE="submit" VALUE="Submit Form"> throws 
Submit Button<BR> Exception 
<INPUT TYPE="reset" VALUE="Clear Values"> { 
Reset Button. int iArgIndex = Q; 
<P> // -- Loop through all of the args passed into the application 
</FORM> 


while (iArgIndex < args. length) 
{ 
String thisArg = args[iArgIndext+] ; 
GenericArgType arg = getArg(thisArg) ; 
// -- Set the argument and (possibly) increase the arg index. 
if (arg != null) 
iArgIndex = arg.set(args, iArgIndex) ; 
} // -- end while 
} // -- end process 
// -- Look for an argument type that matches the passed-in target 
protected GenericArgType getArg 
( 


String argTarget 
) 


+ 
Enumeration allArgs = vArgs.elements(); 
GenericArgType foundArg = null; 
// -- Loop through each arg type until we find a match or there are 
// -- no more arg types. 
while (foundArg==null && allArgs.hasMoreElements()) 
{ 
GenericArgType testArg = (GenericArgType)allArgs.nextElement () ; 
if (testArg.argID.equalsIgnoreCase(argTarget) ) 
foundArg = testArg; 
} // -- end while 
return foundArg; 
} // -- end getArg 
} // -- end class ArgProcessor 


Listing Two 


// -- Declare this source to be a part of the CmdLnArg package. 


3 anguage. Users are able package CmdLnArg; 
r internal calls. 


// -- Make use of shipped packages for Vector, String, StringBuffer classes 
import java.util.*; 


public abstract class GenericArgType 
{ 


: public String argID = null; 
ike calls to DLLs, kernel APIs, & interrupts. protected boolean wasSet; 
public GenericArgType 
“...CEnvi has virtually replaced ReXX and the “ff you are a C Programmer, then this product ( 

String argID 

) 


DOS Batch language in my office.” [CEnvil] is really a dream come true.” 


Al Stevens, Dr. Dobbs Journal Brian Proffit, OS/2 Magazine { 
December 1994 January 1995 this.argID = argID; 
wasSet = false; 
} // -- end constructor 
public boolean wasSet 


( 


http://www. M@ir } 


Re, { 
Relpep: ® return wasSet; 
Phone: 617 391-6595 e Fax: 617391-3842 ¢ BBS: 617 391-3718 e Internet: nombas@nombas.com } // -- end wasSet 


64 Salem Street Medford, MA 02155 (continued on page 98) 
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Presenting a more comfortable way 


to configure hard-disk partitions. 


Introducing PartitionMagic 2.0. 







Ouch! Modifying a hard-disk partition used to be a very painful process. 
Now with PartitionMagic 2.0, you can dynamically resize your hard-disk 
partitions and FAT clusters in minutes—without shredding your 
data. Just imagine a magical world where you can: shrink, expand 
and move FAT and HPFS partitions with the wave of a mouse; use 
separate partitions to install multiple operating systems; protect your 
code base; and safely test beta code. And there aren't any TSR’s or device 


drivers to create compatibility issues. 


Reveal up to 40% more disk space by ephiciently resizing clusters. 





“| Believe it or not, inefficient FAT clusters can 
PERCENT OF WASTED HARD DISK SPACE 


©1995 POWERQUEST CORP 


waste up to 40” of the storage space of a single 
256 MB-511 MB partition Boo ot aa on af 
wets 8 IS chusters : partition with 32K clusters. PartitionMagic 2.0 


512 MB-1023 MB partition 


ition luster 
erg iia lets you visually resize partitions and clusters to 








SOG isin reveal hundreds of megabytes of wasted disk 


with 32 K clusters 





40% 
storage space (even when using disk compression 


ACTUAL AMOUNT OF WASTED SPACE DEPENDS UPON THE NUMBER AND SIZE OF YOUR FILES 





software like Stacker and DriveSpace). 





Make FDISK and FORMAT hassles disappear—easily! 


PartitionMagic 2.0’s patent-pending technology replaces perilous DOS utilities like 


FDISK and FORMAT with an intuitive, point-and-click interface. Just use your 





mouse to easily configure your PC precisely the way you want—no wonder it won 
BYTE Magazine's Best of Comdex/Fall 1995 Award. WINNER 
Discover the wonders of PartitionMagic 2.0 for Windows 95 & DOS for just $49.95, 
and for OS/2 & DOS for only $69.95. Just call PowerQuest at 1-800-379-2566 


and mention code #PQDDJ16 to order your copy today. For more information, white 





papers (and magic) visit our home page at: http://www.powerquest.com. 


ion 
yer 2.0 


Partition Magic 
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public abstract int set // -- Declare this source to be a part of the CmdLnArg package. 
a ; package CmdLnArg; 
tring args[], 


int iThisIndex // -- Make use of shipped packages for Vector, String, StringBuffer classes 
) import java.util.*; 
throws 
Exception public class ArgReqArgType extends GenericArgType 
Mas 
} // -- end GenericArgType public StringBuffer argDest = null; 
public ArgReqArgType 
( 
String argID, 
ich StringBuffer argDest 
Listing Three i ead 
{ 
// -- Declare this source to be a part of the CmdLnArg package. super (argID) ; 
package CmdLnArg; this.argDest = argDest; 
} // -- end constructor 
// -- Make use of shipped packages for Vector, String, StringBuffer classes public int set 


import java.util.*; 
String args[], 


public class WordArgType extends GenericArgType it iThisIndex 
{ ) 
public boolean argDest; throws 
public WordArgType Exception 
( 
String argID, { 
boolean argDest if (args.length <= iThisIndex) 
throw new Exception("Command line param " 
{ + argID 
+ " must be followed by a string"); 
super (argID) ; // -- We can't directly change the string, so truncate it and add 
this.argDest = argDest; // -- what we want. 
} // -- end constructor argDest.setLength(Q) ; 
public int set argDest.append (args [iThisIndex] ) ; 
( wasSet = true; 
String args[], return iThisIndex + 1; 
int iThisIndex } // -- end set 
) } // -- end class ArgReqArgType 
if (!wasSet) 
{ e ,e ° 
argDest = !argDest; Listing Five 
wasset = true; 
} // -- end if // -- Declare this source to be a part of the CmdLnArg package. 
return iThisIndex; import CmdLnArg.*; 
} // -- end set 
} // -- end class WordArgType // -- Make use of shipped packages for Vector, String, StringBuffer, 
// -- System classes 
import java.util.*; 
import java.io.*; 
class Go 
{ 
// -- Set by cmd line arguments 
static boolean bVerbose false; 


static StringBuffer inputName 
static StringBuffer outputName 
static StringBuffer to 

Static StringBuffer sWidth 
static StringBuffer sTabSize 


new StringBuffer("") ; 
new StringBuffer("") ; 
new StringBuffer ("TextWriter") ; 
new StringBuffer("") ; 
new StringBuffer("") ; 


nou wo uw ou a 


DEVICE DRIVER ED. 


Lesson #1: Write VxDs for Performance 


static Vector vArgs = new Vector(); 





public static void main 


( 
String args[] 
) 


“If you aren't writing protected mode 


{ 
drivers today, you will tomorrow. wo 
processArgs (args) ; 


} // -- end try 


Future versions of Windows give 
you no alternative. Fortunately, 
VTOOLSD makes it simple.” 


— Jon Thomason, Microsoft Windows Kernel Group Manager 


catch (Exception e) 


e.printStackTrace(); 
iReturn = 1: 
} // -- end catch 
System.exit (iReturn) ; 
} // -- end main 
static void processArgs 
( 


String args[] 
) 


throws 
Exception 


Get up to speed with VrooisD,™ the best 
toolkit for building virtual device drivers (VxDs) 
for Windows. Send for detailed information or 
find us now on the Web. 


ArgProcessor processor = new ArgProcessor (args) ; 
add(processor, new ArgReqArgType("-in", inputName)) ; 
add(processor, new ArgReqArgType("-out", outputName)) ; 
add(processor, new ArgReqArgType("-to", to)); 
add(processor, new ArgReqArgType("-width", sWidth)); 
add(processor, new ArgReqArgType("-tabsize", sTabSize)); 





WordArgType verboseArg = new WordArgType("-verbose", false) ; 
add(processor, verboseArg) ; 





\7 Vireo Software 

~ "~~ Tel 508-264-9200 Fax 508-264-9205 
Gold Award Winner http:/ f world.std.com /~vireo/ 

PC Plus Magazine Vireo@vireo.com 


21 Half Moon Hill, Acton, MA 01720. VToo1sD is a trademark of Vireo Software, Inc. 
Microsoft is a registered trademark and Windows is a trademark of Microsoft Corporation. 


WordArgType includeRefs = new WordArgType("-NoRefs", true); 
add(processor, includeRefs) ; 


WordArgType refSections = new WordArgType("-NoSections", true) ; 
add(processor, refSections) ; 


WordArgType refPage = new WordArgType("-NoPages", true); 
add(processor, refPage) ; 
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WordArgType horzRule = new WordArgType("-HR", true) ; 
add(processor, horzRule) ; 


processor.process() ; 
checkSomethingSet () ; 


// -- Print the results back to the user. 


System.out.println("Input name:" + inputName) ; 
System.out.println("Output name:" + outputName) ; 
System.out.println("to:" + to); 
System.out.println("width:" + sWidth) ; 
System.out.println("tabsize:" + sTabSize) ; 


if (verboseArg.wasSet()) 


System.out.print ("Verbose was set to "); 
else 

System.out.print("Verbose left at the default of "); 
System. out.print1n(String.valueOf(verboseArg.argDest)) ; 


if (includeRefs.wasSet () ) 

System.out.print("IncludeRefs was set to "); 
else 

System.out.print("IncludeRefs left at the default of "); 
System. out. print1n(String.valueOf(includeRefs.argDest) ) ; 


if (refSections.wasSet () ) 

System.out.print("RefSections was set to "); 
else 

System.out.print("RefSections left at the default of "); 
System. out.println(String.valueOf(refSections.argDest) ) ; 


if (refPage.wasSet ()) 

System.out.print("RefPages was set to "); 
else 

System.out.print("RefPages left at the default’ of "); 
System. out.print1ln(String.valueOf (refPage.argDest) ) ; 


if (horzRule.wasSet() ) 

System.out.print("HR was set to "); 
else 

System.out.print("HR left at the default of "); 
System. out.println(String.valueOf(horzRule.argDest) ) ; 


} // -- end processArgs 
// -- Adds an argument type to the processor and to our vector so we can 
// -- later make sure somethine was set. 
protected static void add 
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ArgProcessor processor, 
GenericArgType argType 
) 


{ 

processor.add(argType) ; 

vArgs.addElement (argType) ; 

} // -- end add 
// -- Prints info and generates and exception of nothing is set 
protected static void checkSomethingSet 


) 
throws 
Exception 


Enumeration allArgs = vArgs.elements(); 
boolean bAnythingSet = false; 
while (bAnythingSet==false && allArgs.hasMoreElements () ) 
{ 
GenericArgType thisArg = (GenericArgType)allArgs.nextElement () ; 
if (thisArg.wasSet () ) 
bAnythingSet = true; 
} // -- end while 
if (!bAnythingSet) 
[ 
System.out.println("Valid arguments requiring arguments:") ; 
System.out.println(" -in"); 
System.out.println(" -out"); 
System.out.println(" -to"); 
System.out.println(" -width"); 
System.out.println(" -tabsize") ; 
System.out.println(); 
System.out.println("Valid word arguments:") ; 


System.out.println(" -verbose") ; 
System.out.println(" -NoRefs") ; 
System.out.println(" -NoSections") ; 


System.out.println(" -NoPages") ; 
System.out.println(" -HR"); 


throw new Exception("No valid command-line arguments found") ; 
} // -- end if 


} // -- end checkSomethingSet 
} // -- end class Go 


(continued on page 100) 
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(continued from page 99) CClearSpiralTask (POSITION pos) { m_Pos = pos; m_pSpiral=NULL; } 
virtual ~CClearSpiralTask() { delete m_pSpiral; } 
UNDO/REDO virtual void Do(CSpiralDoc*) ; 
virtual void Undo(CSpiralDoc*) ; 
virtual LPCSTR GetDescription() { return "Clear"; } 
private: 
er POSITION m_Pos; // Needed for Do() 
Listing One CSpiral* m_pSpiral; // Needed for Undo() ; 
a3 
// task.h - Definitions of Undo/Redo Tasks class CClearAllTask : public CTask { 
// NOTES: 1. Strings should be in resources, but leaving them here makes the public: 
// examples clearer. CClearAl11Task () { ) 
// 2. The virtual functions are not really inline, but they are so short that virtual ~CClearAllTask() ; 
// it makes it easier to read. virtual void Do(CSpiralDoc*) ; 
LLLLLTTTLTTTTTTTT TTT TTT TTA TTT TATA TTT AAT ATTA TTA TAA TATA virtual void Undo(CSpiralDoc*) ; 
virtual LPCSTR GetDescription() { return "Clear All"; } 
class CTask : public CObject { private: 
public: CSpiralList m_SpiralList; // Needed for Undo() 
CTask () { /* empty */ } a3 
virtual ~CTask() { /* empty */ } 
virtual void Do(CSpiralDoc*) = @; 
virtual void Undo(CSpiralDoc*) = cake 
virtual LPCSTR eee ae a Listing Two 
private: 
CTask(const CTask&) ; // Disable copy constructor /* task.cpp - Implementation of undo/redo tasks */ 
CTask& operator=(const CTask&); // Disable assignment operator 
33 #include "stdafx.h" 
class CCreateSpiralTask : public CTask { #include "Spiral.h" 
public: #include "Foreman.h" 
CCreateSpiralTask(CSpiral* pSpiral) { m_pSpiral = pSpiral; } #include "SpiraDoc.h" 
virtual ~CCreateSpiralTask () { delete m_pSpiral; } #include "SpiraVw.h" 
virtual void Do(CSpiralDoc*) ; #include "Task.h" 
virtual void Undo(CSpiralDoc*) ; 
virtual LPCSTR GetDescription() { return "Draw"; } #ifdef _DEBUG 
private: #undef THIS_FILE 
CSpiral* m_pSpiral; // Needed for Do() static char BASED_CODE THIS_FILE[] = __FILE__ 
ie #endif 
class CMoveSpiralTask : public CTask { /* Undo/Redo Actions */ 
public: 
CMoveSpiralTask(CSpiral* pSpiral, const CSize& size) #define INVALIDATE_SPIRAL() pSpiralDoc->UpdateAllViews (NULL, @, m_pSpiral); \ 
: m_Size(size) { m_pSpiral = pSpiral; } pSpiralDoc->m_updateRect = m_pSpiral->m_rectBounding; 
virtual ~CMoveSpiralTask () { } IIALIALLIAL ALLA LAAT T 
virtual void Do(CSpiralDoc*) ; void CCreateSpiralTask: :Do(CSpiralDoc* pSpiralDoc) 
virtual void Undo(CSpiralDoc*) ; { 
virtual LPCSTR GetDescription() { return "Move"; } // Before Do(), we own the spiral. After Do(), the doc owns the spiral. 
private: pSpiralDoc->m_SpiralList.AddTail(m_pSpiral) ; 
CSpiral* m_pSpiral; // Needed for Do() and Undo() INVALIDATE_SPIRAL() ; 
CSize m_Size; // Needed for Do() and Undo() m_pSpiral = NULL; 
3 } 
class CClearSpiralTask : public CTask { , 
public: (continued on page 102) 
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void CCreateSpiralTask: :Undo(CSpiralDoc* pSpiralDoc) 

{ 
m_pSpiral = pSpiralDoc->m_SpiralList.RemoveTail () ; 
INVALIDATE_SPIRAL() ; 


} 
SILTLTLTTLTTTTTTTTTAAT LTT TAT 
void CMoveSpiralTask: :Do(CSpiralDoc* pSpiralDoc) 


{ 
INVALIDATE_SPIRAL() ; 
m_pSpiral->Move(m_Size) ; 
INVALIDATE_SPIRAL () ; 
} 
void CMoveSpiralTask: :Undo(CSpiralDoc* pSpiralDoc) 
{ 


INVALIDATE_SPIRAL () ; 

CSize size(-m_Size.cx, -m_Size.cy); 
m_pSpiral->Move (size) ; 
INVALIDATE_SPIRAL() ; 


} 
LELTLTTTTTTLTTTTTTTTT TTT TATA 
void CClearSpiralTask: :Do(CSpiralDoc* pSpiralDoc) 


{ 

// Need to remember the spiral preceding the one being deleted so if 
// the user does an undo, we know where to put it back. 

CSpiralList& SpiralList = pSpiralDoc->m_SpiralList; 
POSITION prevPos = m_Pos; 
SpiralList.GetPrev(prevPos) ; 
m_pSpiral = SpiralList.GetAt(m_Pos) ; 
SpiralList.RemoveAt (m_Pos) ; 
INVALIDATE_ SPIRAL () ; 
m_Pos = prevPos; 

} 

void CClearSpiralTask: :Undo(CSpiralDoc* pSpiralDoc) 

{ 


CSpiralList& SpiralList = pSpiralDoc->m_SpiralList; 
m_Pos = SpiralList.InsertAfter(m_Pos, m_pSpiral) ; 
INVALIDATE_SPIRAL() ; 

m_pSpiral = NULL; 


} 
LLLLTLTTTLTTTT TTT TTT TTT ATTA TTT TTT 
CClearAllTask: :~CClearAllTask () 


if 
while (!m_SpiralList.IsEmpty()) 
delete m_SpiralList.RemoveHead () ; 
} 
void CClearAllTask: :Do(CSpiralDoc* pSpiralDoc) 
{ 


CSpiralList& documentSpiralList = pSpiralDoc->m_SpiralList; 
while (!documentSpiralList.IsEmpty () ) 
m_SpiralList .AddTail (documentSpiralList .RemoveHead()) ; 


pSpiralDoc->UpdateAllViews (NULL) ; 


void CClearAllTask: :Undo(CSpiralDoc* pSpiralDoc) 
{ 
CSpiralList& documentSpiralList = pSpiralDoc->m_SpiralList; 
while (!m_SpiralList.IsEmpty ()) 
documentSpiralList .AddTail (m_SpiralList .RemoveHead()); 
pSpiralDoc->UpdateAllViews (NULL) ; 


e e 
Listing Three 
/* foreman.h - Class definition of undo history manager */ 


// Forward Declarations. By having these, we do not have to load 
// other include files. 


class CSpiralDoc; 
class CTask; 
class CSpiral; 


// Type definitions 

#ifdef WIN32 

typedef CTypedPtrList<CObList,CSpiral*> CSpiralList; 
typedef CTypedPtrList<CObList,CTask*> CTaskList; 
typedef CArray<CPoint,CPoint> CPointArray; 

#else 

#include "template.h" 

fendif // WIN32 


// CForeman Class Definition 
class CForeman 


{ 

public: 
CForeman() ; 
~CForeman(); 


void SubmitTask (CTask*) ; 

void Undo(); 

void Redo(); 

// The "Can" functions are used by OnCommandUpdate 

// to figure out when to grey out the menu option. 

BOOL CanRedo(); 

BOOL CanUndo(); 

// The "GetDescription" functions are used by OnCommand 

// to describe the actions waiting to be redone and undone. 

LPCSTR GetRedoDescription() ; 

LPCSTR GetUndoDescription() ; 

// The foreman is an aggregate member of the document. SetDocument is 
// called by the document's ctor to provide a pointer back to the doc. 
void SetDocument (CSpiralDoc* pSpiralDoc) ; 
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// After a do or undo, make sure the user can see it. m_pSpiralDoc->SetModifiedFlag () ; 


void MakeLastTaskVisible(CSpiralDoc* pSpiralDoc) ; } 
private: void CForeman: :Undo() 
// Linked list of tasks. { 
CTaskList m_taskList; m_pSpiralDoc->m_updateRect .SetRectEmpty () ; 
// The position and the index both indicate the next if (CanUndo()) { 
// task to undo, but in slightly different forms. // Undo the current entry, then backup in the list. 
POSITION m_DoUndoPosition; // GetPrev returns the object at the *current* position 
int m_iDoUndoIndex; // indicated by m_DoUndoPosition, then sets m_DoUndoPosition 
// Remember which document this foreman is related to. // back one link. A better name is "GetCurrentAndMoveBackPosition" 
CSpiralDoc* m_pSpiralDoc; CTask* pTask = m_taskList.GetPrev(m_DoUndoPosition) ; 
iE --m_iDoUndoIndex; 
inline BOOL CForeman::CanRedo() {return m_iDoUndoIndex < m_taskList.GetCount () ;} pTask->Undo(m_pSpiralDoc) ; 
inline BOOL CForeman::CanUndo() {return m_iDoUndoIndex > @; } } 
inline void CForeman::SetDocument (CSpiralDoc* pSpiralDoc) // If the user undid everything, then the document is unchanged 
{ m_pSpiralDoc = pSpiralDoc; } // relative to how it started. Clear the "modified" flag to show this. 


// Small bug: we do not account for File:Save properly in this example. 
if (m_taskList.GetCount() == 9) 
ich m_pSpiralDoc->SetModifiedFlag (FALSE) ; 
Listing Four if (!m_pSpiralDoc->m_updateRect.IsRectEmpty () ) 
MakeLastTaskVisible(m_pSpiralDoc) ; 






/* foreman.cpp - Implementation of undo history manager */ } 
void CForeman: :Redo() 
#include "stdafx.h" t 
#include "Spiral.h" m_pSpiralDoc->m_updateRect.SetRectEmpty () ; 
#include "Foreman.h" if (CanRedo()) f{ 
#include "Spiradoc.h" // Advance to the next entry and execute it. 
#include "SpiraVw.h" m_iDoUndoIndex++; 
#include "Task.h" if (!m_DoUndoPosition) 
m_DoUndoPosition = m_taskList.GetHeadPosition() ; 
#ifdef _DEBUG else 
#undef THIS_FILE m_taskList.GetNext (m_DoUndoPosition) ; 
static char BASED_CODE THIS_FILE[] = __FILE__; CTask* pTask = m_taskList.GetAt (m_DoUndoPosition) ; 
#endif pTask->Do(m_pSpiralDoc) ; 
m_pSpiralDoc->SetModifiedFlag () ; 
/* Foreman */ } 
CForeman: : CForeman () if (!m_pSpiralDoc->m_updateRect.IsRectEmpty () ) 
{ MakeLastTaskVisible(m_pSpiralDoc) ; 
m_iDoUndoIndex = @Q; } 
} LPCSTR CForeman: :GetRedoDescription() 
CForeman: :~CForeman () { 
{ if (CanRedo()) { 
while (m_taskList.GetCount() > @) POSITION nextPos = m_DoUndoPosition; 
delete m_taskList .RemoveTail () ; if (!nextPos) 
} nextPos = m_taskList.GetHeadPosition() ; 
void CForeman: : SubmitTask(CTask* task) else 
{ m_taskList.GetNext (nextPos) ; 
while (m_iDoUndoIndex < m_taskList.GetCount () ) return m_taskList.GetAt (nextPos) ->GetDescription() ; 
delete m_taskList.RemoveTail (); } 
m_DoUndoPosition = m_taskList.AddTail (task) ; return ""; 
m_iDoUndoIndext+; : 
task->Do(m_pSpiralDoc) ; (continued on page 104) 
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7 
LPCSTR CForeman: :GetUndoDescription() 
{ 
if (CanUndo()) { 
return m_taskList .GetAt (m_DoUndoPosition) ->GetDescription() ; 
5 


return ""; 


// Find the currently active view and scroll it so that the 
// last rect invalidated by a task is visible. 

void CForeman: :MakeLastTaskVisible(CSpiralDoc* pSpiralDoc) 
f 


// Get the active view so it can be updated. 

CMDIChildWnd * pChild = 

( (CMDIFrameWnd* ) (AfxGetApp () ->m_pMainWnd) ) ->MDIGetActive() ; 
if ( !pChild ) 


return; 

CView * pView = pChild->GetActiveView() ; 

if ( !pView || !pView->IsKindOf( RUNTIME_CLASS(CSpiralView) )) 
return; 


// Compare the window rect to the update rect and act appropriately. 
CSpiralView* pSpiralView = (CSpiralView*) pView; 
CClientDC dce(pView) ; 
pView->OnPrepareDC (&dc) ; 
CRect clientRect; 
pView->GetClientRect (&clientRect) ; 
if (!dce.PtVisible(pSpiralDoc->m_updateRect.TopLeft () ) 

it !de.PtVisible(pSpiralDoc->m_updateRect.BottomRight()) ) { 
// Try to center the spiral of interest in the current view. 
CPoint ptCenter = pSpiralDoc->m_updateRect.TopLeft () ; 
int xDesired = ptCenter.x - clientRect.Width() / 2; 
int yDesired = ptCenter.y - clientRect.Height() / 2; 
pSpiralView->ScrollToPosition(CPoint(xDesired, yDesired)) ; 
// This next line is required for proper updates with splitters 
pSpiralView->GetDocument ()->UpdateAllViews (NULL, @, NULL); 


Listing Five 
// Excerpts from SpiraVw.CPP 


void CSpiralView: :OnUpdateEditUndo(CCmdUI* pCmdUI) 

{ 
CString str("Undo "); 
str = str + GetDocument ()->m_Foreman.GetUndoDescription() + "\tCtr1+z"; 
pCmdUI->SetText (str) ; 
pCmdUI->Enable (GetDocument ()->m_Foreman.CanUndo()) ; 


} 
void CSpiralView: :OnEditUndo () 
t 
GetDocument ()->m_Foreman.Undo() ; 
} 
void CSpiralView: :OnUpdateEditRedo(CCmdUI* pCmdUI) 
{ 
CString str("Redo "); 
str = str + GetDocument ()->m_Foreman.GetRedoDescription() + "\tCtr1+A"; 
pCmdUI->SetText (str) ; 
pCmdUI->Enable (GetDocument () ->m_Foreman.CanRedo()) ; 
} 
void CSpiralView: :OnEditRedo() 
{ 


GetDocument ()->m_Foreman.Redo(); 


NEST 


e e 

Listing One 

typedef struct { 
nuint16 CheckSum; 
nuintl6 Length; 
nuint16 ConnectionID; 
nuinti16 | SequenceNumber; 
nuint16 PacketVersionID; 
nuinti6 Reserved; 
nuinti6 Function; 
nuint16 SubFunction; 
nuinti6 Flags; 
nuint16 Status; 

} NPHeader; 


/* NPHeader structure is part of every NP packet going on the wire. */ 
void doNPEspressoMaker (NPConnection *hConn, ECB *reqECB, ECB *replyECB) ; 
{ 


/* Get a pointer to the request */ 
NPRequestBuffer *stdReq = reqECB->ECB_Fragment [1] .FragmentAddress; 
/* Get a pointer to the reply packet */ 
NPReplyBuffer *stdReply = replyECB->ECB_Fragment [1] .FragmentAddress; 
/* Extract the SubFunction number from the NP Header */ 
int replySize = @; 
int SubFunction = NSwapHiLo16(stReq->Header.SubFunction) ; 
switch (SubFunction) { 
/* Remotely fake a local control pannel key press */ 
case EX_MAKER_FAKE_KEY: { 
/* the key ID to fake is in the first byte */ 
nuint8 key = stdReq->DataBuffer [@] ; 
espressoAddKeyToQueue (key) ; 
break; 
} 


/* Remote client is requesting the current status */ 


Dr. Dobb's Journal, February 1996 





case EX_MAKER_REQUEST_STATUS: { 
memcpy (stdReq->DataBuffer, espressoGetStatus(), 
replySize = SIZEOF_EspressoStatus) ; 
break; 
} 
/* Display a message on the Maker LCD Display */ 
case EX_MAKER_POST_MESSAGE: { 
/* Get NP Lenght field, convert HiLo to Native */ 
int msgSize = NSwapHiLo16(reqECB->Header.Length) ; 
msgSize -= (SIZEOF_NPHeader - 4); 
espressoPostLCD(stdReq->DataBuffer, msgSize) ; 
} 
/* don't forget to report an error otherwise */ 
default: stdReply->Header.Status = NSwapHiLo16 (NPER_UNKNOWN_REQUEST) ; 
3 
/* Always reply */ 
replyECB.ECB_FragmentCount = 2; 
replyECB->ECB_Fragment [1] .FragmentLength = replySize + SIZEOF_NPHeader; 


Listing Two 


typedef struct _eventDataBlock { 
struct _eventDataBlock *edbNext; 


void *edbConenction; 

int edbFunction; 

int edbSubFunction; 

int edbStatus; 

int edbRequestID; 

long edbDataSize; 

nuint8 edbDataBlock[42@] ; 
} EDB; 


/* The EDB Structure as defined in the NPCAPI.H file; the DLL API. */ 


int TMainWindow::sendNP(int subFunction, unsigned char *req, int reqSize, char 
*reply) 
if 


EDB edb; 
memset (&edb, @, sizeof(edb)) ; 
edb.edbFunction = EX_ESPRESSO_CLASS; 
edb.edbSubFunction = subFunction; 
if (edb.edbDataSize = reqSize) 
memcpy (edb.edbDataBlock, req, reqSize) ; 
int error = ::NPSendExtendedNP(hConn, &edb) ; 
// If that request generated a reply, transfer it to the user 
if (!error && edb.edbDataSize && reply) 
// that guy's buffer better be big enough! 
memcpy(reply, edb.edbDataBlock, edb.edbDataSize) ; 


return error; 
int TMainWinow: :fakeKeyPress(int keyID) 


unsigned char key = (unsigned)keyID; 
sendNP (EX_MAKER_FAKE_KEY, &key, 1, NULL); 


} 
e e 
Listing One 
/* o_client.c -- This is the "Old way" of doing a file transfer. Set up the 


* connection, then go into a loop, alternating between recv()s and write()s. 


int get_file_from_server(char * servername, char * filename) 


struct hostent FAR * he; 
SOCKET sock; 

int nRc; 

struct sockaddr_in addr; 
char buf[1@24] ; 

int hFile; 

int recvlen; 


hFile = open(filename, _O_CREATE | _O_WRONLY) ; 
he = gethostbyname(servername) ; 


if (the) 
{ 


} 

sock = socket (PF_INET, SOCK_STREAM, IPPROTO_TCP) ; 
if (sock == INVALID_SOCKET) 

{ 


} 

/* We want to bind to any available address we have. */ 
addr.sin_family = PF_INET; 

addr.sin_port = @; 

addr.sin_addr.s_addr = INADDR_ANY; 


return ERR_NO_HOSTNAME; 


return ERR_NO_SOCKET; 


nRc=bind(sock, (struct sockaddr FAR *)&addr, sizeof(struct sockaddr) ); 
if(nRce != 0) 
{ 


(continued on page 100) 
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closesocket (sock) ; 
return ERR_BIND_FAILED; 


/* Now connect to the server. We'll just use a normal blocking 
* connect, because it's easiest for this example. */ 
addr.sin_port = htons(KNOWN_PORT) ; 

addr.sin_addr.s_addr = *(unsigned long *) he->h_addr; 


nRe = connect(sock, (struct sockaddr FAR *)&addr, sizeof(struct sockaddr)); 
if(nRce != 0) 
{ 

closesocket (sock) ; 

return ERR_CONNECT_FAILED; 


/* Here we enter our loop. The calls are done sequentially, and each 
* must wait for it's respective kernel subsystem to complete the 

* operation before continuing. */ 

while((recvlen = recv(sock, buf, 1024, @)) > @) 

{ 


write(hFile, buf, recvlen); 


closesocket (sock) ; 
return; 


Listing Two 


/* o_server.c -- This is the "Old way" of doing a file transfer. Set up the 
* connection, then go into a loop, alternating between read()s and send()s. 


*/ 


int give_file_to_client(char * filename) 
{ 
SOCKET sock, SocketID; 
int nRc; 
struct sockaddr_in addr; 
int fileptr = @; 
int hFile = open(filename, _O_RDONLY) ; 
int bytesread; 
sock = socket (PF_INET, SOCK_STREAM, IPPROTO_TCP) ; 


if (sock == INVALID_SOCKET) 
{ 


return ERR_NO_SOCKET; 
} 
/* Bind to a known port, so the client knows where to find us. */ 
addr.sin_family = PF_INET; 
addr.sin_port = htons (KNOWN_PORT) ; 
addr.sin_addr.s_addr = INADDR_ANY; 


nRc = bind(sock, (struct sockaddr FAR *)&addr,sizeof(struct sockaddr)); 
if(nRce != 0) 
{ 


closesocket (sock) ; 
return ERR_BIND_FAILED; 


/* now listen(), and wait for the client to try to connect */ 
nRc = listen(sock, 2); 
if(nRe != @) 
{ 
closesocket (sock) ; 
return LISTEN_FAILED; 


SocketID = accept(sock, (struct sockaddr FAR *)&addr, 
sizeof(struct sockaddr_in)); 

if (SocketID == INVALID_SOCKET) 

{ 


closesocket (sock) ; 
return ACCEPT_FAILED; 


/* Here we enter our loop. The calls are done sequentially, and each 
* must wait for it's respective kernel subsystem to complete the 

* operation before continuing. */ 

while((bytesread = read(hFile, buf, 1924)) > @) 

C 


send(SocketID, buf, bytesread, @); 


closesocket (SocketID) ; 
closesocket (sock) ; 


Listing Three 


* client.c -- The new and faster way of doing a file transfer. The buffers 
* will be filled and emptied as soon as the network and file kernel 

* subsystems, respectively, are able. First, establish the connection with 
* the server. Create the socket using the overlapped I/0 flag. Recall that 
* we are assuming TCP. Note that in many places, psuedo-code is used. At 
* the time it was written, the WinSock 2 SDK was not yet available. 


#define DATA_BUF_SIZE 1024 
#define BUF_POOL_SIZE 10 


HANDLE file_thread; 
DWORD file_thread_id; 


HANDLE network_thread; 
DWORD network_thread_id; 


typedef struct _buf_pool_entry 
{ 


OVERLAPPED overlapped; 
WSABUF data; 
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int last_buffer; 
} BUF_POOL_ENTRY; 
BUF_POOL_ENTRY buffer_pool [BUF_POOL_SIZE] ; 


HANDLE FileHandle = Q; 
SOCKET SocketID = @; 


DWORD NetworkThread(LPVOID threadparams) ; 
int get_file_from_server(char * servername, char * filename) 
{ 

struct hostent FAR * he; 

SOCKET sock; 

int nRc; 

struct sockaddr_in addr; 


he = gethostbyname(servername) ; 


if (!he) 
{ 
return ERR_NO_HOSTNAME ; 
} 
sock = WSASocket (PF_INET, SOCK_STREAM, IPPROTO_TCP, 
NULL, // we're just using TCP, skip protocol 
// independence stuff for now 
NULL, // we'll not worry about socket groups, 
// either 
WSA_FLAG_OVERLAPPED) ; 


if (sock == INVALID_SOCKET) 
if 


} 


/* We want to bind to any available address we have. */ 
addr.sin_family = PF_INET; 

addr.sin_port = 9; 

addr.sin_addr.s_addr = INADDR_ANY; 


return ERR_NO_SOCKET; 


nRce = bind(sock, (struct sockaddr FAR *)&addr, sizeof(struct sockaddr)); 
if(nRe != @) 
{ 
closesocket (sock) ; 
return ERR_BIND_FAILED; 
} 


/* Now connect to the server. We'll just use a normal blocking 
* connect, because it's easiest for this example. */ 
addr.sin_port = htons (KNOWN_PORT) ; 

addr.sin_addr.s_addr = *(unsigned long *) he->h_addr; 


nRe = connect(sock, (struct sockaddr FAR *)éaddr, 
sizeof(struct sockaddr)); 


if(nRe != @) 
{ 
closesocket (sock) ; 
return ERR_CONNECT_FAILED ; 
} 
SocketID = sock; 
/* initialize the buffer pool */ 
for(i = @; i < BUF_POOL_SIZE; i++) 
{ 
buffer_pool[i] .overlapped.hEvent = CreateEvent (NULL, FALSE, FALSE,NULL) ; 
if (buffer_pool [i] .overlapped.hEvent == NULL) 
{ 
// clean up all the objects and exit. We failed initialization 
} 
buffer_pool[i].data.buf = malloc (DATA_BUF_SIZE) ; 
if (buffer_pool [i] .data.buf == NULL) 
{ 
// clean up all the objects and exit. We failed initialization 
} 
buffer_pool[i] .data.size = DATA_BUF_SIZE; 
buffer_pool[i].last_buffer = FALSE; 
} 
/* Send all of the buffers in the pool to WSARecv, so they're ready for 
* incoming data. */ 
for(i = 0; i < BUF_POOL_SIZE; it+) 


{ 
if (WSARecv(SocketID, &(buffer_pool[i].data), 1, &bytesread, &flags, 
&(buffer_pool[i].overlapped), NULL) == @) 
{ 
// Function succeeded immediately. Set the event object ourselves 
SetEvent (buffer_pool [i] .overlapped.hEvent) ; 
} 
else 
{ 
if (WSAGetLastError() == WSA_IO_PENDING) 
/* exactly what we expected */ 
else 
/* we've failed, clean up and return */ 
} 
} 


/* Create the network thread. The network thread waits for network 
* operations to complete, and then takes those (full) buffers and sends 
* them to the filesystem via WriteFile. */ 
network_thread = CreateThread(NULL, 9, NetworkThread, NULL, 
®, // run immediately 
&network_thread_id) ; 
/* Wait until network thread is complete */ 
return SUCCESS; 


DWORD NetworkThread(LPVOID threadparams) 


(continued on page 108) 
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(continued from page 107) if(++pool_ptr >= BUF_POOL_SIZE) 


pool_ptr = Q; 
{ } 
int nRc; /* when bytesread is zero, we're don 
int pool_ptr = @; while(bytesread > @ ); 
BOOL firstpass = 1; 
DWORD bytesread, flags; /* Wait for file thread to complete before leaving */ 
BOOL success; ExitThread (QL) ; 
int file_ptr = 9; } 
do /* Everytime a write to the filesystem completes, take the buffer, and call 
{ | * WSARecv() so that the network subsystem can fill it back up. */ 
/* No need to check the return code. Since we specified WSA_INFINITE, DWORD FileThread(LPVOID threadparams) 
* the only time it will return is when our event is signalled. */ { 
WSAWaitForMultipleEvents(1, &(buffer_pool[pool_ptr] .overlapped.hEvent) , int nRc; 
FALSE, WSA_INFINITE, FALSE) ; int pool_ptr = @; 
/* WaitForMultipleEvents() blocks until the next recv() buffer 
* is filled. We check (below) to see how many bytes were DWORD bytesread, flags; 
* actually read, and then send off to be written to disk. */ BOOL success; 
success = WSAGetOverlappedResult (SocketID, int file_ptr = Q; 
&(buffer_pool[pool_ptr] .overlapped) , 
&bytesread, FALSE, &flags) ; do 
/* If we've received the event notification, but the number { 
* of bytes is zero, then the connection;s been closed. /* We don't need to check return code. Since we specified INFINITE, 
/ * the only time it will return is when our event is signalled. */ 
if(bytesread == @) WaitForSingleObject (&(buffer_pool[pool_ptr] .overlapped.hEvent) , 
{ INFINITE) ; 
buffer_pool[i].last_buffer = TRUE; success = GetOverlappedResult (FileHandle, 
// set the event, so that the file thread will receive this "EOF" &(buffer_pool[pool_ptr] .overlapped) , 
SetEvent (buffer_pool [pool_ptr] .overlapped.hEvent) ; &bytesread, FALSE) ; 
// we're done receiving /* If we've received the event notification, but the number 
break; * of bytes is zero, then the connection;s been closed. */ 
} if (buffer_pool[i].last_buffer == TRUE) 
buffer_pool[pool_ptr] .overlapped.Offset = file_ptr; { 
file_ptr += bytesread; // we're done 
break; 
if(WriteFile(FileHandle, buffer_pool[pool_ptr].data.buf, bytesread, J 
&bytes_written, &(buffer_pool[pool_ptr] .overlapped)) == TRUE) buffer_pool[pool_ptr] .overlapped.Offset = file_ptr; 
file_ptr += bytesread; 
// function succeeded immediately. Set the event object ourselves /* Buffer is ready to be returned to the protocol stack for reading */ 
SetEvent (buffer_pool [pool_ptr] .overlapped.hEvent) ; if (WSARecv(SocketID, &(buffer_pool[pool_ptr].data), 1, &bytesread, 
} &flags, &(buffer_pool[pool_ptr].overlapped), NULL) == @) 
if (firstpass) 
{ // function succeeded immediately. Set the event object ourselves 
// This is the first buffer to be filled. Create the SetEvent (buffer_pool [pool_ptr] .overlapped.hEvent) ; 
// thread that handles completion of file I/0 } 
file_thread = CreateThread(NULL, @, FileThread, NULL, if(+t+tpool_ptr >= BUF_POOL_SIZE) 
@, // run immediately pool_ptr = @; 
&file_thread_id) ; } 
firstpass = FALSE; /* when bytesread is zero, we're done 
} while(bytesread > @ ); 
ExitThread (QL) ; 


@ oye 
Get Interactive! |)" 
e ial CTAaAC e e /* server.c -- The new and faster way of doing a file transfer. The buffers 


* will be filled and emptied as soon as the network and file kernel 

* subsystems, respectively, are able. First, establish the connection with 

* the server. Create the socket using the overlapped I/O flag. Recall that we 
* 

* 


maia(> 


£14S_ieit (1). 
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are assuming TCP. Note that in many places, psuedo-code is used. At 
the time it was written, the WinSock 2 SDK was not yet available. 
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nRe = bind(sock, (struct sockaddr FAR *)&addr, sizeof(struct sockaddr)); // good, that's what we expected 
if(nRe != @) else 
{ /* we've failed, clean up and return */ 
closesocket (sock) ; } 
return ERR_BIND_FAILED; fileptr += DATA_BUF_SIZE; 
} } 
/* Now listen(), and wait for the client to try to connect */ /* Create the file I/0 thread. The file I/O thread waits until the buffers 
nRe = listen(sock, 2); * have been filled, and then takes those full buffers and sends them out 
if(nRe != Q) * to the network (via WSASend(). */ 
{ file_thread = CreateThread(NULL, @, FileThread, (LPVOID) (LPINT) &fileptr, 
closesocket (sock) ; ®, // run immediately 
return LISTEN_FAILED; &file_thread_id) ; 
} /* Wait until network thread is complete */ 
SocketID = accept(sock, (struct sockaddr FAR *)éaddr, return SUCCESS; 
sizeof(struct sockaddr_in)); } 
if (SocketID == INVALID_SOCKET) DWORD NetworkThread(LPVOID threadparams) 
{ { 
closesocket (sock) ; int nRc; 
return ACCEPT_FAILED; int pool_ptr = @; 
} BOOL firstpass = 1; 
/* Initialize the buffer pool */ DWORD bytesread, flags; 
for(i = 9; i < BUF_POOL_SIZE; i++) BOOL success; 
{ int file_ptr = *(LPINT) threadparams; 
buffer_pool [i] .overlapped.hEvent = CreateEvent (NULL, FALSE, FALSE, NULL) ; do 
{ 
if (buffer_pool[i] .overlapped.hEvent == NULL) /* No need to check the return code. Since we specified WSA_INFINITE, 
* the only time it will return is when event is signalled. */ 
// clean up all the objects and exit. We failed initialization WSAWaitForMultipleEvents(1, &(buffer_pool[pool_ptr] .overlapped.hEvent) , 
} FALSE, WSA_INFINITE, FALSE) ; 
buffer_pool[i].data.buf = malloc (DATA_BUF_SIZE) ; /* WaitForMultipleEvents() blocks until the next send() buffer 
if (buffer_pool[i] .data.buf == NULL) * is empty. We then send it back to the filesystem to be refilled. 
* If this is the last buffer, we just complete. */ 
// clean up all the objects and exit. We failed initialization success = WSAGetOverlappedResult (SocketID, 
} &(buffer_pool[pool_ptr].overlapped) , 
buffer_pool[i].data.len = DATA_BUF_SIZE; &bytesread, FALSE, &flags) ; 
buffer_pool[i].last_buffer = FALSE; if (buffer_pool [i] .last_buffer == TRUE) 
} { 
/* Send all of the buffers in the pool to WSARecv, so they're ready for // we're done 
* incoming data. */ break; 
for(i = 0; i < BUF_POOL_SIZE; i++) } 
{ buffer_pool[pool_ptr].overlapped.Offset = file_ptr; 
buffer_pool[i] .overlapped.Offset = fileptr; file_ptr += DATA_BUF_SIZE; 
if (ReadFile(FileHandle if (ReadFile(FileHandle, buffer_pool[pool_ptr].data.buf, 
&(buffer_pool[i].data.buf), DATA_BUF_SIZE, &bytesread, DATA_BUF_SIZE, &bytes_written, 
&(buffer_pool [i] .overlapped)) == @) &(buffer_pool[pool_ptr].overlapped)) == TRUE) 
{ { 
// function succeeded immediately. Set the event object ourselves // function succeeded immediately. Set the event object ourselves 
SetEvent (buffer_pool [i] .overlapped.hEvent) ; SetEvent (buffer_pool [pool_ptr] .overlapped.hEvent) ; 
} } 
else file_ptr += DATA_BUF_SIZE; 
if (WSAGetLastError() == WSA_I0_PENDING) (continued on page 111) 
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if(+t+tpool_ptr >= BUF_POOL_SIZE) 
pool_ptr = @; 
} 
/* when bytesread is zero, we're done 
while(bytesread > @ ); 


ExitThread (@L) ; 
} 
/* Everytime a write to the filesystem completes, take the buffer, and call 
* WSARecv() so that the network subsystem can fill it back up. */ 
DWORD FileThread(LPVOID threadparams) 
{ 
int nRc; 
int pool_ptr = @; 


DWORD bytesread, flags; 
BOOL success; 
int file_ptr = Q; 


do 
{ 
/* We don't need to check the return code. Since we specified INFINITE, 
* the only time it will return is when our event is signalled. */ 
WaitForSingleObject (&(buffer_pool [pool_ptr] .overlapped.hEvent) , 
INFINITE) ; 
success = GetOverlappedResult (FileHandle, 
&(buffer_pool [pool_ptr] .overlapped) , 
&bytesread, FALSE) ; 
/* If we've received the event notification, but the number 
* of bytes is zero, then we've reached EOF. */ 
if(bytesread == Q) 
{ 


buffer_pool[i].last_buffer == TRUE; 
// set the event 
SetEvent (buffer_pool[pool_ptr] .overlapped.hEvent) ; 
// we're done reading 
break; 
} 
buffer_pool[pool_ptr] .overlapped.Offset = file_ptr; 
file_ptr += bytesread; 
/* This buffer is ready to be returned to protocol stack for sending */ 
if (WSASend (SocketID, &(buffer_pool[pool_ptr].data), 1, &bytesread, 
&flags, &(buffer_pool[pool_ptr].overlapped), NULL) == @) 


// function succeeded immediately. Set the event object ourselves 
SetEvent (buffer_pool [pool_ptr] .overlapped.hEvent) ; 

} 

if (firstpass) 


// This is the first buffer to be filled. Create the 
// thread that handles completion of file I/O. 
network_thread = CreateThread(NULL, @, NetworkThread, threadparams, 
0, // run immediately 
&network_thread_id) ; 
firstpass = FALSE; 
} 
if(++pool_ptr >= BUF_POOL_SIZE) 
pool_ptr = @; 
} 
/* when bytesread is zero, we're done 
while(bytesread > @ ); 


/* Wait for the network thread to complete */ 
ExitThread (@L) ; 





EXAMINING ROOM | 


Listing One 





RWCString wonderTool ("Rogue") ; 
wonderTool += "Wave tools.h++"; 
cout << wonderTool << endl; // Prints "RogueWave tools.htt+" 
( 't=' concatenates) 
RWCString aString = "I am 34.5 years young"; 
RWCRegexp re1("[@-9]+*[\\.]*[0-9]*"); // Construct regexp object. 
// Recognizes decimal #s. 
aString(rel) = "184.9"; 
cout << aString << endl; // Prints "I am 184.9 years young" 


Listing Two 


size_t ind = aString.index ( "young" ); 
aString(ind,®) = "old"; 


cout << aString << endl; // Prints "I am 184.9 years old" 

RWCTokenizer tok ( aString ); // Class RWCTokenizer performs 
// strtok-like functions. 

cout << tok() << endl; // Prints "I" 


cout << tok() << endl; // Prints "am" 
cout << aString << endl; // Prints "I am 184.9 years old" 


(continued on page 112) 
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(continued from page 111) XYPoint ( unsigned mo, unsigned day, unsigned year ) 
xDate ( day, mo, year), yValue(@.0), ptDescription() 


e e 
Listing Three () 
// Default constructor. 
XYPoint () 
RWDate today; xDate(), yValue(-9999.99), ptDescription() { } 
cout << today << endl; // Prints the current date (default constructor) // Copy constructor. 
XYPoint ( const XYPoint& xyp ) 
RWDate weekAgo = today-7; // Subtracts 7 days from today. xDate(xyp.xDate) , 
RWDate myBirthDay ( 24, 2, 61); // m,d,y constructor. yValue(xyp.yValue) , 
ptDescription(xyp.ptDescription ) { } 
cout << myBirthDay.weekDayName() << endl; // Prints "Friday"! // Assignment operator = 
cout << today - myBirthDay << endl; // Prints number of days I've been alive. XYPoint& operator=(const XYPointé& xyp ) 
{ 


xDate = xyp.xDate; 


Listing Four yValue = xyp.yValue; 


ptDescription = xyp.ptDescription; 


// This example alters the date string for French-speaking users. // Equality == operator 
RWLocale& french = *new RWLocaleSnapshot ("fe") ; RWBoolean operator==( const XYPoint& xyp ) const 
cout << myBirthday.asString ( 'x', french ) << endl; { 


if ( xDate == xyp.xDate ) 
return TRUE; 


16h H else 
Listing Five return FALSE; 
} 
struct XYPoint { // Less then < operator. 
RWDate xDate; // Independent (X) value. RWBoolean operator<( const XYPoint& xyp ) const 
float yValue; // Dependent (Y) value. { 
RWCString ptDescription; // Text associated w/point. if ( xDate < xyp.xDate ) 
i return TRUE; 
else 
return FALSE; 
e e e } 
Listing Six 
class XYPoint 
{ e e 
ern Listing Seven 
RWDate xDate; // Independent (X) value. RWTValSortedVector<XYPoint> myValCurve; // Create a new curve of XYPoints. 
float yValue; // Dependent (Y) value. 
RWCString ptDescription;// Text associated w/point // Insert 1/1/95, 2/1/95, 3/1/95, 4/1/95 data points into curve 
public: myValCurve.insert ( XYPoint (1, 1, 95, 1000.0, "Point 1" ) ); 
// Main constructor. myValCurve.insert ( XYPoint (1, 2, 95, 1050.0, "Point 2" ) ); 
XYPoint ( unsigned mo, unsigned day, myValCurve.insert ( XYPoint ( 1, 4, 95, 2000.0, "Point 4" ) ); 
unsigned year, float val, const char* descrip ) : myValCurve.insert ( XYPoint ( 1, 3, 95, 1500.0, "Point 3" ) ); 
xDate ( day, mo, year ), yValue(val), 
ptDescription ( descrip ) { } // Value-based collection now has 4 points in correct order. 


// Key-only constructor. 

XYPoint locator (1, 1, 95 );  // Create a temporary point to be 
// used for searching. 

myValCurve.remove ( locator ); // Remove the first point only. 


cout << myValCurve.entries() << endl; // Prints '3', since 3 pts are left. 


myValCurve.clear(); // Removes all elements. 


The professional defect 
r f SSi € RWTPtrSortedVector<XYPoint> myPtrCurve; // Pointer-based analog of above. 
@ 
tracking fool myPtrCurve.insert ( new XYPoint ( 1, 95, 1000.0, "Point 1" ) ); 


1 ’ 
myPtrCurve.insert ( new XYPoint ( 1, 2, 95, 1050.0, "Point 2" ) ); 


// Pointer-based collection must explicitly free the dynamically 
// allocated points! This can be the source of huge memory leak! BEWARE! ;-) 


myPtrCurve.clearAndDestroy(); // Deletes each XYPoint and 
// removes from collection. 


Listing Eight 


Data Based Advisor, June 1995 


RWvostream& operator<< ( RWvostream& s ) const 


s << xDate << yValue << ptDescription; 


return s; 
For the latest 
or € ea es RWvistream& operator>> ( RWvistream& s ) 
{ 
demo & product news: s >> xDate >> yWalue >> ptDescription, 
return s; 
} 
Listing Nine 


RWFileManager fm("mydb.dat"); // Create file manager class on a disk file. 
RWBTreeOnDisk bt(fm); // Construct B-Tree for the file manager. 


RWCString myAddress ( "11915 Merry Lane" ); 


RWOffset loc = fm.allocate ( myAddress.binaryStoreSize() ); 
fm.SeekTo ( loc ); 

fm << myAddress; 

bt.insertKeyAndValue ( "Perry", loc ); 


Listing Ten 


RWOffset foundLoc = bt.findValue ( "Perry" ); 
fm.SeekTo ( foundLoc ); 


Archimedes Software ® 303 Parkplace Center Suite 125 ¢ lige eet 
Kirkland, WA 98033 ® Phone: 1-800-338-1453 e 
Ht.archimedesinc.com (/pub/devtools) cout << "My address is: " << foundAddress << endl; 
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PROGRAMMER’S WORKBENCH re [* RULES ------- 99 nn nnn nner rrr rrr rrr rrr rr rrr an */ 


30 
31 program: 
coat 32 condition 
Listing One ay Pee 
34 | program error 
1 %{ a0) :4 
2 #include "ytab.h" 36 
3 extern int yylval; 37 /* This production just collects various productions into one production, 
4 %)} 38 to reduce the number of different actions that must be coded in the 
5 39 next higher production. 
6 %% AQ */ 
7 Al 
8 [A-z]. f 42 condition: 
9 yylval = *yytext - 'A'; 43 compoundcondition 
10 return VARIABLE; 44 |  specialcondition 
11 } 45 |  quotecondition 
i2 46 ; 
13 [a-z] f{ 47 
14 yylval = *yytext - ‘a'; 48 /* Special conditions that exclude any other condition * / 
15 return VARIABLE; 49 
16 ; 5@ specialcondition: 
17 Si BLANKS /* fieldname = NULL symbol */ 
18 [@-9]+ { So). AG /* fieldname >= minimum field value */ 
19 yylval = strtol(yytext, (char **)NULL, 9); 53 3 
20 return INTEGER; 54 
21 } 55 /* One or more ordinary conditions (simple comparisons) */ 
22 56 
23 Ox[@-9a-fA-F]+ { 57 compoundcondition: 
24 yylval = strtol(yytext, (char **)NULL, 16); 58 
25 return INTEGER; 59 simplecondition /* Begin the parse */ 
26 } 60 |  compoundcondition simplecondition %prec AND /* AND simplecondition */ 
27 61! compoundcondition comma simplecondition /* OR simplecondition */ 
28 [-()=+/*\n] return *yytext; 62 ; 
29 63 
30 [ \t]+ : 64 /* ordinary conditions -- single comparisons and ranges */ 
pl 65 
oe. « yyerror("Unknown character") ; 66 simplecondition: 
67 value /* fieldname = value */ 
68 |  globvalue fieldname like value */ ; 
toch 69 ; opcode value * fieldname >=,>,<,<= value * 
Listing Two 70 | value rangeop value /* fieldname >= valuei AND fieldname <= value2 */ 
71 ; 
1 *{ 72 
2 #include <stdio.h> 73 /* Quoted string comparison -- convert a quoted string to a sequence of 
3 %} 74 ANDed equalities. This is how we search for a string with embedded 
4 75 spaces when Bookware will only search for individual words. 
5 %token INTEGER VARIABLE 76 */ 
6 left ‘+! op ce | 
7 left '*' '/! . 
8 (continued on page 114) 
9 wf 
10 static int variables([26] ; 
11 % e 
5 For Borland C/C++, Mic 
13 %% 
14 
15 program: 
16 program statement '\n' 
17 | program error '\n' = { yyerrok; } 
18 | /* NULL */ 
19 ; 
20 
21 statement: 
22 expression = { printf("%d\n", $1); } 
23 | VARIABLE '=' expression = { variables[$1] = $3; } 
oa: § 
whe) 
4 en tea RTKernel is a professional, high-performance, real-time 
28 | VARIABLE = { $$ = variables[$1]; } multitasking system for MS-DOS and Embedded 
29 | expression '+' expression = { $$ = $1 + $3; } Systems. It can use DOS device drivers and BIOS, and 
30 | expression '-' expression = { $§ = $1 - $3; } runs other DOS applications as a task - even Windows! 
31 | expression '*' expression = { $$ = $1 ¥* $3; } _ 
32 | expression '/' expression = { $$ = $1 / $3; } RiKernel is loaded with features: an unlimited 
a '(' expression ')' = ( $$ = $2; } number of tasks, excellent performance, a full set of 


inter-task communication functions (semaphores, mailboxes, 

synchronous message-passing), real and protected mode 

Listing Three Support, drivers for up to 38 COM ports and Novell’s IPX 
services, and lots more... 


: : : ae */ : ease acd eet es It’s ROMable and very compact (about | 6k 
sé parser for use wit = an 1sua asic ' it | 

3 /* Ian E. Gorman, ActiveSystems Inc., Ottawa, Ontario, Canada */ code, 6K data), making It ideally suited for Embedded 

i Systems. 

: fe Cade, enpyed to Show only the yace grammar */ RTKernel is well-documented and easy to use. All 

7 /* DERINITIONS --------------------------------------------------<<-++- */ hardware drivers always come with source code; kernel 

8 %{ source code available at extra charge. No 

9 = e e 

10 #include <ctype.h> run-time royalties. 

11 #include <stdarg.h> Join thousands of satisfied customers! 

12 #include "dbinfo.hpp" /* includes "parsetab.hpp", "token.hpp" */ . . 

13 #include "logfile.hpp" 

14 

15 %} 

16 

17 %token CHARSTRING GLOBSTRING 

18 “token ',' 

19 %token AND 

20 


%token OPCODE RANGEOP 
21 %token ALL BLANKS 


Free demo disk! Ask for 





22 token '"' 

23 Demo D 
24 /* OPCODE and CHARSTRING have strings associated with them. http://www.on-time.com 
25 The other terminals are not associated with strings. */ ftp.on-time.com 
a Internet: into@on-time.com 
27 %% 
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(continued from page 113) 


78 quotecondition: 


79 quote stringlist quote /* completed a quoted string */ 
80 ; 

81 

82 quote: 

83 oes /* tell lex to discard nonchar symbols */ 
84 ; 

85 

86 stringlist: 

87 value /* fieldname = value */ 

88 | stringlist value /* AND fieldname = value */ 

89 ; 

99 /x '(' ')', ',', OPCODE are ignored inside a stringlist */ 

91 /* BLANKS and ALL are treated as ordinary strings inside a string list */ 
92 

93 


94 /* Values for alpha fields must be quoted in Bookware searches, values for 


96 */ 


numeric fields must not be quoted. 


98 value: 


This is where we decide what to do. 


CHARSTRING 


/* Wild cards -- xxxx% will become -- fieldname like 'xxxx%' 
Values must be quoted in Bookware searches. 


numeric fields must not be quoted. 


*/ 


globvalue: 
GLOBSTRING 


rangeop: 
RANGEOP 


opcode: 
OPCODE 


comma : 
f 


GRAF/DRIVE PLUS 4.5 
Printer/Plotter Graphics for DOS 


Publication-quality hard copy 
graphics for Microsoft-compatible C 
compilers, Borland C, and Borland 
Pascal. Borland programmers use the 
same functions for screen and hard 
copy graphics, with almost no 
change to their source code. Also in- 
cludes Borland SVGA drivers with 
mouse support. You'll see our drivers 
in commercial software for desktop 
publishing, business charts, invest- 
ment analysis, maps, and science 
and engineering. "Highly recom- 
mended"—Jeff Dunteman, Dr. Dobbs. 

Full-resolution output to Laser- 
Jet, Epson & IBM dot matrix, 
DeskJet, DeskJet Color, PaintJet, 
PostScript (mono/color), Canon laser 
& ink jet, Epson Stylus, HP plotters, 
color dot matrix, obscure printers too 
numerous to mention, PCX, TIF, DXF, 
WMF, BMP, Al, CGM, more file for- 
mats. (DTP addon req'd for file for- 
mats and less common printers.) 

More than 140 functions, 
including arc, bar, bar3d, circle, 
drawpoly, fillpoly, ellipse, fillellipse, 


line, outtext, pieslice, putpcx, 
putimage, rectangle, sector, setcolor, 
setfillpattern, setfillstyle, setlinestyle, 
setpalette, settextjustify, setviewport, 
textheight, textwidth. 

Print to LPT1-4, COM1-4 or disk, 
portrait or landscape, any size from 1 
inch to 5 feet e Use PostScript fonts 
on a PostScript printer e Use resident 
or downloaded fonts on a LaserJet e 
Use default and scalable stroke fonts 
on any printer e Print spooler e Print 
both vector and raster graphics e 
scale, dither, and print PCX, TIFF, 
BMP, Targa, GIF files, and screen 
dumps e Print without spawning a 
separate program (except Borland 
DPMI-32) e Print without clearing 
your graphics or text screen e Net- 
work-compatible e Does not require a 
graphics screen e Includes libs for 
real mode, 16-bit protected mode, 
and Borland DPMI-32. 

Personal License $149, Develop- 
ers with royalty-free distribution 
$299. DTP Drivers $99. 30-day m/b 
guarantee. 


FLEMING SOFTWARE BOX 569 OAKTON, VA 22124 
(703) 591-6451 
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This is where we decide what to do. 


Listing Four 


/* Compound logical condition */ 
/* Ian E. Gorman, ActiveSystems Inc., Ottawa, Ontario, Canada */ 


compoundcondition: 
simplecondition /* Begin the parse */ 


$$ = $1; 


i compoundcondition simplecondition %prec AND /* AND simplecondition */ 
$$ = $1; 

$$->ConCat(" AND "); 

$$->ConCat ($2->Value()) ; 

scan->ParseList->Discard ($2) ; 


| compoundcondition comma simplecondition /* OR simplecondition */ 


Nr RRP RPP RP RP PPR 
BOoOnrtaunlFwnrQowowonoanlfwoner 


21 $$ = $1; 

22 $$->ConCat(" OR "); 

23 $$->ConCat ($3->Value()); 

24 scan->ParseList->Discard ($2) ; 

25 scan->ParseList->Discard ($3) ; 

26 } 

27 ; 

28 

29 simplecondition: 

30 value /* fieldname = value */ 

31 { 

32 $$ = new(scan->FieldName) ParseItem_t; 

33 scan->ParseList->AddAtTail (S$) ; 

34 $$->ConCat(" ="); - 

35 $$->ConCat ($1->Value()); 

36 scan->ParseList->Discard($1) ; 

37 

38 |; globvalue /* fieldname like value */ 

39 { /* more code here */ } 

49 | opcode value /* fieldname >=,>,<,<= value */ 
Al 

42 $$ = new(scan->FieldName) ParseItem_t; 

43 scan->ParseList->AddAtTail ($$) ; 

44 $$->ConCat(" "); 

45 $$->ConCat ($1->Value()) ; /* opcode */ 
46 $$->ConCat(" "); 

47 $$->ConCat ($2->Value()); /* value */ 
48 scan->ParseList->Discard($1) ; 

49 scan->ParseList->Discard($2) ; 

5@ } 

51 | value rangeop value /* fieldname >= valuei AND fieldname <= value2 */ 
52 { /* more code here */_ } 

53. 3 

54 

55 value: 

56 CHARSTRING 

57 { /* Encloses a string value in single quotes, when the field is not 
58 numeric. */ 

59 if ( scan->FieldNumeric ) { 

60 /* Can put a check here for non-numeric value in numeric field. 
61 If not numeric, YYERROR */ 

62 $$ = $1; 

63 }else { 

64 $$ = new("'") ParseItem_t; 

65 $$->ConCat ($1->Value()); 

66 $$->ConCat("'"); 

67 scan->ParseList->Discard($1); 

68 } 

69 } 

7@ ; 


Listing Five 


1 /* Produce SQL query segment from data for one field */ 
2 /* Ian E. Gorman, ActiveSystems Inc., Ottawa, Ontario, Canada */ 


3 

4 /* This function is a wrapper for the yacc parser, yyparse() */ 
5 

6 char * cParse::FieldParse( 

7 FldItem_t * Field /* list of field data: name, opcode, expression */ 
8 

9 { 

10 char * Result = NULL; 

1 int 1} 

12 yy_parse yaccparse = yy_parse(YSTACKSIZE, ystates, yvals); 
13 yy_scan * yscan; 

14 

15 if ( ! Field ) 

16 return NULL; 

17 

18 yscan = new( /* set up the token separator */ 

19 Field->Expr(), 

20 Field->Name(), 

23 Field->IsNumber(), /* 1 for numeric fields, @ otherwise */ 
22 Field->NullValue(), 

23 Field->FirstValue() 

24 ) yy_scan; 

25 

26 if ( ! yscan ) 

a | return Result; 

28 

29 if ( ! yaccparse.yyparse(yscan) ) { 

30 /* parse the expression into SQL query */ 

31 Result = new char[strlen(yscan->output->Value())+1]; /* success */ 
32 strepy(Result, yscan->output->Value()); 

33 } 
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Ke delete yscan; 
36 

37 return Result; 
38 } 

e e ° 
Listing Six 


/* Abbreviated version of class yy_parse from MKS lex and yacc */ 
class yy_parse { 
public: 

yy_scan* scan; // pointer to scanner 

int yydebug; // if set, tracing if compiled with YYDEBUG=1 


yy-parse(int = 159); // constructor for this grammar 
yy_parse(int, short *, YYSTYPE *); // another constructor 


~yy_parse(); // destructor 
int yyparse(yy_scan * ps); // parse with given scanner 
void yyreset() { reset = 1; } // restore state for next yyparse() 
void setdebug(int y) { yydebug = y; } 
// The following are useful in user actions: 
void  yyerrok() { yyerrflag = 9; } // clear error 


void yyclearin() { yychar = -1; } // clear input 
int YYRECOVERING() { return yyerrflag != 9; } 
}; 


Listing Seven 


char * cParse: :MakeSQL( 
cSearchList * ListManager /* Field list manager for current database */ 


char * StrSQL; 

char * Temp; 
FldItem_t * Element; 
enum _FieldOP LeadingOpCode, FollowingOpCode; 


/* new string -- SQL query */ 


if ( ! ListManager ) 
return NULL; 


/* Start with SQL command verb and data base name */ 
QueryString = new("SELECT * FROM dbn WHERE (") ParseItem_t; 


/* Assume no opcode before first expression */ 
LeadingOpCode = eNOP; 


for ( Element = ListManager->Head () 
; Element != NULL 
; Element = ListManager->Next (Element) 


) 
FollowingOpCode = ( ListManager->Next (Element) 
? ListManager->Next (Element) ->OpCode () 
: eNOP ); 
/* open parenthesis at beginning of several ORed field conditions */ 
// if ( FollowingOpCode == eOR && LeadingOpCode != eOR ) 
// QueryString->ConCat("(") ; 
/* parse each field condition, enclose result in parentheses + / 
QueryString->ConCat("(") ; 
if (! (Temp = FieldParse(Element)) ) { 
LogErrorDLL(__FILE__, --LINE__, 
"NULL expression ‘while parsing query, Parsed OK to: %s\n", 
QueryString->Value() 
) ° 


delete QueryString; 
return NULL; /* incomplete string would be no good */ 


QueryString->ConCat (Temp) ; 
delete Temp; 
QueryString->ConCat(")") ; 


/* close parenthesis at end of several ORed field conditions */ 
// if ( LeadingOpCode == eOR && FollowingOpCode != eOR ) 
// QueryString->ConCat (")") ; 
/* if not the last field condition, append the connector to next */ 
if ( ListManager->Next (Element) != NULL ) 
QueryString->ConCat (SQLtoken(FollowingOpCode) ) ; 
LeadingOpCode = FollowingOpCode; 
} 
QueryString->ConCat (") ;"); 
StrSQL = new char [strlen(QueryString->Value())+1]; 
if ( StrSQL) f 
strepy(StrSQL, QueryString->Value()) ; 


delete QueryString; 
return StrSQL; 





ParseItem_t * QueryString; 
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Looking for an 
HTML Book 


Michael Swaine 


his month I thought I’d share my ex- 

perience in looking for a good HTML 

book. In addition, there’s the third in- 

stallment in my survey of alternative 
programming paradigms, or “Languages 
That Are Not C.” 

I got roped into a project to develop a 
one-day, intensive course in HTML for 
raw beginners. My task was to find a text 
for the course, a book on which we could 
base the lectures. I suspected right from 
the start that this was either impossible or 
unwise. Any book that could be covered 
in a day would have to be pretty skimpy. 
A book that we could give the students 
for further study, sure, that might make 
sense, but a text for the course? I was 
skeptical. 

Over a dozen books later, my suspicion 
had turned into a conviction. No book was 
going to work. I made the obvious pro- 
posal: that we write the class materials from 
scratch and not try to cut corners. Having 
done the research, though, I found that I 
was in a good position to recommend 
HTML books to the students. Or maybe to 
others. Because it occurred to me that, while 
some of the books I read were written for 
the raw beginner, some assume a level of 
sophistication that you would only find— 
well, among readers of this magazine. 

So. If you sometimes get questions 
from people hoping to write HTML, if 
you occasionally write or expect to write 
HTML, if you have responsibility for 
maintaining a Web site or for maintain- 
ing in-over-their-heads Web site main- 
tainers, or if you have noticed that ev- 
erybody in the world seems to want to 
put up a Web page and you figure you 
might as well put together a course or 
seminar and make a buck off this mad- 
ness, here’s my take on the HTML books 
I examined. 

Although I read more, I’ve whittled the 
list down to five books. There are prob- 
ably good books I’ve left off the list, but 
every book on the list is worth buying. 
Some of these books were first published 
in 1994, which makes them unusably an- 
cient. They’re all good enough that their 
publishers should be updating them reg- 
ularly, but I haven’t tried to project which 
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ones will have new 1996 editions out by 
the time you read this. 


Quick Study 

HTML Manual of Style (Ziff-Davis Press, 
1994, ISBN 1-56276-300-8) is Larry Aron- 
son’s first book, and he’s to be com- 
mended. The book is short (132 pages), 
simple, and clearly organized. By the end 
of the first 30 pages, he’s introduced and 
exemplified most of the vocabulary of 
HTML 2.0. 

Aronson gets purity points for recom- 
mending that links be incorporated into 
the flow of a paragraph rather than laid 
out in lists or detached from context 
(“Click HERE for my resume.”) In this way 
he honors the hypertext intent of the Web. 
Incorporating links into the flow of the 
text works great for budding hyperfiction 
writers and researchers trying to smooth 
the footnote bumps out of their reports. 
I imagine, though, that we’re going to see 
more and more violations of this design 
ideal as more and more people bend the 
Web to uses for which it was not origi- 
nally intended. Aronson has good advice 
on the quirks of particular browsers, in 
particular in how they handle partial URLs. 

HTML Manual of Style lacks some ref- 
erence material that I’d like to see. There’s 
no complete reference on URLs, nothing 
on CGI or multimedia or server issues. 
And the HTML tag reference could be 
more complete; it lists, but doesn’t ex- 
plain, the values for tag attributes. 

Aronson uses real Web pages as exam- 
ples and does real critiques on them. There 
are two schools of thought on examples: 
Some people think that only made-up ex- 
amples can get across their pedagogical 
points, while others think that real-world 
examples are the best way to point out 
real problems. I’m with the latter group. 
Maybe it’s because I get a perverse plea- 
sure Out of watching real people’s work 
being picked apart. Aronson isn’t cruel, 
but he is honest. He cites errors and eval- 
uates their seriousness. Each of the pages 
he’s chosen exemplifies some virtue, so 
most of what he has to say is positive (and 
useful). One of the best pages he presents 
is by John December. The first 30 pages 





of this book are the closest I got in my re- 
search to what I was looking for: a truly 
short course in HTML. The rest of this book 
is style advice and reference. A clear, well- 
organized HTML manual. 


Massive Tome 

John December and Neil Randall have 
produced a huge book entitled The 
World Wide Web Unleashed (Sams Pub- 
lishing, 1994, ISBN 0-672-30617-4). It at- 
tempts to cover everything about the 
Web: how to connect to the Web as a 
user, reviews of browsers, a tour of Web 
sites, HTML, and the future of electron- 
ic commerce. The book is 1058 pages 
long; nearly 100 pages of that is appen- 
dices, and these are nearly all links to 
useful sites. These sites are the most im- 
portant part of the book. John Decem- 
ber, well known on the Web for his lists 
of resources and informed commentary, 
wrote the HTML and Web-development 
sections. Randall and several others 
joined December in writing the less tech- 
nical material. 

I guess I'll give the authors purity points 
for wondering why Web browsers make 
it possible to print out pages. Larry Aron- 
son knows one answer that should be ob- 
vious to December and Randall: so that 
you can produce decent examples of Web 
pages in a book on Web-page design. 

HTML is covered in the broader con- 
text of designing Web pages. It’s not con- 
cise, but it’s solid. There is nothing sub- 
stantial on CGI or multimedia, and there 
is no comprehensive URL reference — sur- 
prising in a book this fat. 

The book is way fatter than it needs to 
be: The authors are not concise, the very 
useful links in the appendices belong on a 
disk or a disc or a Website, and some of 
the chapters are merely informed or inter- 
esting speculation. Nevertheless, there is a 
lot of good information here, and if you 
are your company’s Web guru, you prob- 
ably will appreciate having it on your shelf. 


No Nonsense 

Mary E.S. Morris takes a no-nonsense ap- 
proach to her subject. Her HTML for Fun 
and Profit (Prentice Hall, 1995, ISBN 
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0-13-359290-1) jumps right into the de- 
tails of setting up a server. By the time 
she gets through with that, she has prob- 
ably weeded out the people who just 
want to mark up documents and has nar- 
rowed down her readership to people 
capable of and willing to take on the 
whole process of creating and publish- 
ing Web pages. 

This 264-page book has more informa- 
tion on the specific topic of relative URLs 
than any book I’ve looked at. I’'d picked 
this topic deliberately as one benchmark 
of completeness. The coverage Morris pro- 
vides would be very useful if you were 
setting up a site that you might later need 
to move to another machine, or that you 
might want to mirror. 


Morris’s coverage of server includes and 
CGI scripting is strong. She gives a good 
introduction for UNIX, Mac, and NT sys- 
tems and provides a number of useful Perl 
scripts. As for HTML specifically, the cov- 
erage is good. The reference table on HTML 
tags doesn’t indicate permissible nesting, 
which some of the other books are clear 
about. Her discussion of forms is clear and 
seems exhaustive. This is a good book for 
people setting up and running Web servers. 


Charting a Course 

Teach Yourself Web Publishing with HTML 
in a Week (Sams Publishing, 1995, ISBN 
0-672-30667-0) is the first of two books on 
HTML by Laura LeMay. The second, which 
I haven't seen, is Teach Yourself More Web 
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by James F Korsh and 
Leonard J. Garrett 





Publishing with HTML in a Week. Now, here 
is a book (two, actually) obviously designed 
for a course. And, equally obviously, not 
for a one-day course. LeMay’s 403-page 
book implicitly makes the case that the one- 
day intensive course is a bad idea. If it takes 
her a week (or two) and she’s bragging 
about it, well.... I found several of the things 
that I was looking for specifically. Her HTML 
reference indicates the permissible nesting 
of tags, and hers is the only book that con- 
tained what I considered a sufficiently 
thoughtful discussion of the pros and cons 
of lumping apparently separate pages into 
one file, linked using named anchors. 

LeMay gives a lot of design advice, in- 
cluding a discussion of storyboarding. Her 
URL reference includes the specification 
for the URL for nonanonymous ftp, which 
is rare in HTML books. She has good ad- 
vice on URLs, such as when not to use File 
URLs. She gives an overview of CGI script- 
ing and imagemaps. Possibly she gets into 
these subjects more deeply in week two. 

LeMay is of the made-up-examples 
school. It works well for her. This is a 
good course book and a good reference; 
although I don’t think I’d call it “the most 
complete HTML reference I have seen” as 
the cover blurb does. 


Duke of URLs 

It's probably foolish to talk about “the most 
complete HTML reference I have seen,” 
since I’m sure I'll see three or four more 
by the time this column sees print. Nonethe- 
less, if I were to nominate a most com- 
plete, it would probably be Jan Graham’s 
HTML Sourcebook (John Wiley & Sons, 
1995, ISBN 0-471-11849-4). This 416-page 
book is an introduction to, and reference 
for, HTML, URLs, HTTP, and CGI scripting. 

The HTML coverage is clear and read- 
able. I found most of the things I was look- 
ing for. The coverage of URLs is the best 
I've seen. Like LeMay, Graham gives the 
URL for nonanonymous ftp; his discussion 
of Gopher URLs suggests, as the other 
books don’t, that you might actually want 
to support the Gopher protocol. He also 
discusses the rlogin URL, personal direc- 
tories using the tilde character, and frag- 
ment reference using the # character. His 
is the only book in which I could find out 
what to do with a filename that includes 
a forward slash. 

The discussion of CGI scripting is most- 
ly an overview with links to tools. There 
is a good chapter on the HTTP protocol, 
and an appendix on MIME. 


Potion for the C-Sick 
The rest of this column is the third in- 
stallment in my ongoing look at alterna- 
tive programming paradigms. 

These tend to be embodied in little lan- 
guages, sometimes in the Jon Bentley sense 
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and sometimes in the sense of a pared- 
down, single-author implementation of a 
paradigm that typically tromps a bigger 
footprint on the disk. Tiny Ada, as it were. 
As it is, in fact, although not this month. 
What I’m looking for when I look at these 
little languages is what makes the paradigm 
distinctive, and the state of its health. My 
interest is not in the merits of the paradigms 
or of the implementation so much as in 
their distinctiveness and their chances for 
survival in the Darwinian struggle. I con- 
fess that this comes out of a blind, a priori 
faith in the value of diversity. Save the 
paradigmatic rain forest, that’s my motto. 


Rewriting ReWrite 

Roy Ward (rward@random.otago.ac.nz) 
has written an interesting little language 
called “ReWrite.” It runs only on the Mac- 
intosh, requiring at least a 68020 and Sys- 
tem 7.0, and will run in emulation on a 
PowerMac. It is a compiled language, and 
the ReWrite compiler is written in ReWrite. 
ReWrite is interesting specifically as a 
testbed for exploring the rewrite-rule pro- 
gramming paradigm. 

Programming using rewrite-rule syntax 
is usually encountered in functional lan- 
guages like Haskell, ML, Miranda, Clean, 
or in the functional mode of Mathemati- 
ca. When you use ReWrite, you feel as 
though you’re using one of these func- 
tional languages. You define functions with 
rewrite rules. Example 1(a) is the definition 
of the factorial function in ReWrite. The 
basic syntax is a list of rules specifying a 
transformation; see Example 1(b). You can 
add conditions (or guards) to these rules; 
Example 1(c) is that factorial function in 
a more-robust form. The modification in- 
side the brackets specifies a condition for 
the match to take place, and the one out- 
side the brackets specifies an additional 
condition (beyond the match) that must 
be satisfied for the rule to apply. More 
precisely, these two forms of rule syntax 
are as in Example 1(d), where name is a 
token, patterns is zero or more patterns 
separated by commas, condition is an 
expression, and results is zero or more 
expressions separated by commas. A pat- 
tern can be a constant (optionally coerced 
to a type), a token (which matches any 
single value, optionally conditioned to a 
type), or a list or portion of a list of val- 
ues. The list representation is somewhat 
Lisp-like, and allows ReWrite to define 
core Lisp functions, as in Example 1(e). 

As is the case with proper functional 
languages, these functions don’t have side 
effects (other than obvious ones like 
screen output). 


No Garbage 


But underneath the rewrite syntax, ReWrite 
is working in an applicative way. That is, 
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factorial [0] -> 1; 


factorial [n] -> n * factorial [n-1]; 


rule [pattern] -> result; 


factorial 0] -> 1: 
factorial [n . int] :; 


n>@ -> n * factorial [n-1]; 


name [patterns] -> results; 


name [patterns] :: 


car | (xz, 


condition -> results; 


reat) | -> x: 





edr | (x, . reat) | -> reet: 


cone | x, rest | -> Ix, 


Example 1: Using ReWrite. 


the code is fully compiled and there is no 
eval mechanism, no garbage collection, 
and no other complicated memory man- 
agement. Functions clean up after them- 
selves, including all the list-processing func- 
tions. And code compiles to “moderately 
efficient” 68020/68030 machine code. Ward 
presents an example program in ReWrite 
and Pascal to find the mth prime. In one 
test, nprime [2000] takes 32 ticks in Pas- 
cal and 134 ticks in ReWrite. This isn’t bad, 
surely, for a language implementation de- 
signed for exploratory purposes and only 
in an early rev, but it does require a lot of 
explicit typing of variables. A naive ReWrite 
version of this program is a lot slower. 


rest}; 





On the other hand, ReWrite is a lot faster 
than Mathematica, which has a similar syn- 
tax. The reason is that Mathematica is in- 
terpreted, and ReWrite is strictly compiled. 
And Mathematica costs money, while 
ReWrite is freeware. 

On the third through fifth hands, Math- 
ematica is a robust, professional, sup- 
ported product that runs on many plat- 
forms, and a major new version of 
Mathematica is due out imminently. I hope 
to write about it soon. 


DDJ 
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C PROGRAMMING 


Quincy 96: 


If You Only GNU 


Al Stevens 


nn Lindsey Williams was the pretti- 

est girl in the sixth grade, which 

made her the prettiest girl in the 

world, at least as far as my world 
extended. Consequently, I was overjoyed 
when the principal teamed us to sell milk 
in the Lorton, Virginia Elementary School 
cafeteria. The Fairfax County School Board 
had allowed that two students could be 
released from class a few minutes early 
to set up the milk line and sell the milk. 
In exchange for our time and service, 
which also meant that we ate alone after 
the shift was over, we each earned a car- 
ton of milk, a significant contribution to 
the economies of our families’ budgets in 
those tough times. It was an assignment 
of some consequence, a matter of duty, 
not to be taken lightly. Besides perform- 
ing an official function and providing eco- 
nomic relief for my own personal daily 
operating expenses, I got to have lunch 
every day with Ann Lindsey Williams, the 
prettiest girl in the sixth grade. 

Billy Alvey came through the line ev- 
ery day, tossed some coins on the table, 
paying a nickel or a dime more than his 
milk cost, and said with a superior smirk, 
“Keep the change.” Billy liked to impress 
Ann Lindsey, although I doubt that he no- 
ticed me. Patiently each day, I followed 
Billy to where he sat down, returned his 
change to him, and explained that we 
were not allowed to keep the change. No 
suggestion of impropriety, graft, bribery, 
kickback, or any such indiscretion, imag- 
inary or otherwise, would be allowed to 
jeopardize my position. 

After several days, and with this sce- 
nario repeating itself each day, Ann Lind- 
sey asked me why it was that we couldn't 
keep the change. I looked around the 
cafeteria, which doubled as an auditori- 
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um for student assemblies and a meeting 
and dance hall for the PTA. I regarded the 
Virginia State flag in one corner, Old Glo- 
ry in the other, the patriotic mural on one 
wall, portraits of George Washington and 
Harry Truman on the other, and said af- 
ter a moment’s thought, “I think it’s be- 
cause we work for the government.” 
Those sure were simpler times. 


GNU Projects 

Recently I undertook a project to devel- 
op a CD-ROM, in conjunction with DDJ. 
I had to choose between that project and 
writing the definitive Minesweeper for 
Dummies for Trudy Neuhaus at IDG 
books. The CD-ROM looked like it would 
be easier. 

Plans for the project include multime- 
dia, interactive, razzle-dazzle displays un- 
der Windows 95. The tutorial content 
comes from three books I’ve written, one 
on programming in general, one on learn- 
ing C, and another on C++. Users will 
switch between the tutorial sessions and 
the programming exercises seamlessly, or 
so the plan goes. A definite must for the 
CD-ROM is a small, common software- 
development environment so that users 
can compile and run exercise programs 
and do some programming on their own. 
The books included that kind of support 
with QBasic, a mainstay of DOS; Quincy, 
a home-grown C interpreter; and GNU 
C++, Similar solutions but three completely 
different development environments. 

I plan to continue to use QBasic for the 
first part of the tutorial, but neither Quin- 
cy nor GNU C++ fit into my vision of an 
integrated, online tutorial environment. 
That requirement has spawned “Quincy 
96,” a new “C Programming” column pro- 
ject kicking off this month. Quincy 96 is 





a Windows 95 version of Quincy that sup- 
ports standard C and C++. 

To review, the Quincy C interpreter runs 
in DOS under the D-Flat user-interface C 
library. I developed the program from an 
earlier version of a K&R interpreter. I in- 
cluded Quincy on the companion diskette 
of the C tutorial book and described it in 
this column last year. The new Quincy is 
not an interpreter. Instead, it is a Windows- 
hosted integrated development environ- 
ment (IDE) that launches C and C++ com- 
pilers to compile and link projects and 
execute the compiled programs. 

Let’s consider the reason for a new 
Quincy by addressing some of the draw- 
backs of the old one. First, the old Quin- 
cy (Version 4) is a source-code interpreter. 
Consequently, it sets no speed records 
when executing C programs. Second, 
Quincy 4 has a few bugs. It works well 
with the tutorial programs in the book, 
but students have managed to uncover 
small quirks in Quincy’s interpretation of 
C. Third, the old Quincy interprets pro- 
grams consisting of one translation unit 
only— one source-code file and its in- 
cluded headers. The standard C library 
functions are implemented, but Quincy 4 
has no linker to link multiple object mod- 
ules in a project. Finally, Quincy 4 is re- 
stricted to interpreting programs written 
in the C language. As such, Quincy 4 of- 
fers little to the C programmer who is 
learning C++. 

C++ code has been interpreted, I am 
told, but writing a C++ interpreter is a big- 
ger chaw than I care to bite off. The effi- 
ciency of an interpreter is a function of 
the size of the language, the complexity 
of the programs being interpreted, and 
the effectiveness of the interpreter itself. 
Needless to say, C++ is big, and C++ pro- 
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(continued from page 121) 

grams are complex. Even if I could get an 
interpreter running in the time I have, it 
probably wouldn’t run very well. 

Having no C++ version of Quincy, I 
used the MS-DOS port of GNU C++ on 
the companion diskette of my C++ tuto- 
rial book. I discussed that experience last 
August, giving a lot of space and favor- 
able comment to GNU C++, a fact com- 
pletely ignored by Richard Stallman of the 
Free Software Foundation when he wrote 
to complain about a different review of 
GNU C++ in the September issue. See the 
December 1995 issue for his letter to the 
editor. 

GNU C and C++ assume a UNIX-like, 
command-line, text-mode development 
environment, which is good enough for a 
free compiler to be given away with a 
book but not quite good enough for what 
I have in mind. Quincy C and GNU C and 
C++ in their current incarnations do not 
fit well into the interactive tutorial envi- 
ronment planned for the CD-ROM project. 

Obviously, something more appropri- 
ate is called for. 


What's GNU for Windows 95? 

Cygnus Support (http://www.cygnus.com) 
has ported GNU C and C++ 2.7.1 to the 
Win32 environment. The port is still in its 
beta configuration, but Cygnus has pro- 
vided what will eventually be a free Win- 
dows-development compiler system. You 
can use GNU C and C++ to write Win- 
dows 95 and Windows NT protected- 
mode, 32-bit, GUI programs as well as 
32-bit DOS command-line programs that 
run in a Windows 95 DOS box. 

I have a compelling reason to use the 
Cygnus port in addition to the incentive 
that it can be freely distributed. GNU C++ 
2.7.1 implements many of the new ANSI 
constructs —RTTI, new-style casts, tem- 
plate improvements, STL, namespaces, mu- 
table, bool, typename, explicit. This com- 
piler is the first I’ve seen for the PC 
platform that implements all these con- 
structs, and it is free. You’ll need a de- 
compression/extraction utility that recog- 
nizes long filenames and works with the 
tar archive and zip compression formats. 
(I use WinZip 6.0, a shareware program 
from Nico Mak Computing. You can 
download and register the shareware ver- 
sion of WinZip from CompuServe.) 


The Good GNUs and the Bad GNUs 

The GNU Win32 package includes both 
compilers, a make utility, the GNU de- 
bugger, many of the GNU utilities, and a 
complete set of standard C and C++ li- 
braries. For my purposes, the compilers 
are almost perfect. First, the C++ compil- 
er provides an early experience in the new 
ANSI C++ constructs. Second, my tutori- 
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al exercises use standard input and out- 
put to demonstrate language features, and 
the GNU compilers fully implement that 
generic interface. But the compilers them- 
selves work in that same austere envi- 
ronment, and I want something that inte- 
grates with the GUI for the CD-ROM 
project. 


Quincy 96, or What's GNU, Pussycat? 
Quincy to the rescue. Quincy 96 is an IDE 


built as a multiple document interface 
(MDI) Windows 95 program. I used Vi- 


The new Quincy is a 
Windows-hosted 
IDE that launches C 


and C++ compilers 





sual C++ 4.0 and the Microsoft Founda- 
tion Class library to build Quincy 96 and 
learned a lot of lessons about that envi- 
ronment— which I will share with you as 
the project progresses. 

Quincy 96 inherits its name from the 
earlier Quincy, which was named after 
my daughter Wendy’s cat. The cat was 
named after Oscar Madison on “The Odd 
Couple.” How’s that, you say? Let me ex- 
plain. Wendy was a fan of Oscar Madi- 
son but unsure of her new kitten’s sex. 
Oscar is a male name. “The Odd Couple” 
was in syndicated reruns, and Jack Klug- 
man, the actor who played Oscar, had 
moved on to playing the medical exam- 
iner “Quincy,” a name that Wendy figured 
would fit either way. Quincy the cat lat- 
er cleared up the gender mystery by 
falling in love with a traveling salescat and 
adding significantly to the cat population 
at our house. 

Quincy 96 has a simple mission. It man- 
ages two kinds of documents: project doc- 
uments and text source-code documents. 
A project document is the same as it is 
with any IDE— a list of source-code files 
that, when compiled and linked, consti- 
tute the program. You build the source- 
code files and add their names to the pro- 
ject list. You can then build the executable 
program file with a command. Quincy 
checks the date/time stamp of the files to 
see what should be recompiled. Quincy 
scans each .c or .cpp file parsing out #in- 
clude preprocessor directives to determine 


all the appropriate dependency conditions. 
When a .c or .cpp source-code file is to 
be compiled, Quincy launches the prop- 
er GNU compiler to run as a threaded pro- 
cess in the background. Quincy intercepts 
warning and error messages from the com- 
piler and presents them to the user, who 
can select from them to go immediately 
to the errant line of code. Quincy launch- 
es the linker when the compiles are com- 
pleted and, optionally, launches the com- 
piled/linked executable program. There 
is no debugger yet, but I am working on 
it. This process, end-to-end, is similar to 
what Turbo C 1.0 did ten years ago but 
in the Windows 95 operating environment 
and with the addition of support for con- 
temporary C++. 

Quincy 96 has an additional mode of 
operation. If no project document is open, 
the build command assumes that the cur- 
rently in-focus .c or .cpp document is a 
stand-alone program to be compiled and 
linked. This mode permits me to run short 
exercise programs like “hello world” with- 
out building a project document for each 
of them. 

Figure 1 is Quincy 96’s application win- 
dow with some source files loaded. 


Design Patterns? 

Remember design patterns? They were a 
hot buzz word a few conferences ago. 
They kind of fizzled out of the popular 
press when software-marketing types 
found out there was nothing to sell. A 
small cadre of developers is still quietly 
working on the process, and some works 
have been published. Among other things, 
design patterns identify common pro- 
gramming problems and their solutions. 
The discussions that follow are design pat- 
terns. Well, sort of. They fit the definition 
of the problem that design patterns ad- 
dress, but I haven’t applied any would-be 
formal pattern methodology in forming 
their descriptions. 

These problems represent routine pro- 
gram operations that should be well un- 
derstood by any MFC programmer and, 
therefore, well documented by Microsoft. 
However, I had to painstakingly ferret out 
their solutions by poring over the docu- 
mentation and online help and by exper- 
imenting. This is a combination of my rel- 
ative inexperience with MFC and the 
poverty of indexes into the mountains of 
MFC reference material. Sometimes there 
was no description of the solution, much 
less the problem. Sometimes the descrip- 
tions were difficult to find because I didn’t 
know where to look or what to look for. 
Sometimes the solutions formed from frag- 
ments of seemingly unrelated information 
scattered about the documentation. The 
Windows API and MFC include hun- 
dreds— maybe thousands— of undocu- 
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mented or poorly documented things that 
programmers need to know about. Pro- 
gramming by folklore. 

Rather than describing each Quincy 96 
source-code file in detail, ll address in- 
dividual programming issues and publish 
the source code that accompanies each 
such discussion. I won’t dwell too much 
on the details of how I figured all these 
things out; I’ll mainly show you the solu- 
tion and hope that it saves you some time 
in your next VC++ MFC project. 


Text Editors 

Quincy is, first of all, a text editor. Before 
you can build any executable programs 
in an IDE, you have to build source-code 
files, and so Quincy is an MDI text edi- 
tor. This month I’ll discuss some of the 
design patterns that fell out of the text 
editing aspects of the design. Next month 
I'll talk about other parts of the project 
and the design patterns that resulted. 

An MDI application can consist of mul- 
tiple instances of multiple document types. 
Each open document is represented by one 
or more document views. Quincy has sev- 
eral document types with one view per doc- 
ument type. Only one instance of the pro- 
ject document type can be open at a time, 


but many instances of 
the source-code doc- 
ument types—C files, 
C++ files, and header 
files— can be open 
for editing. 

The Visual C++ 
Developer Studio al- 
lows you to build an 
MDI application with 
documents that have 
application-specific 
views derived from 
the CEditView class, 
which gives the doc- 
uments the properties 
of a text editor. You 
can open multiple 





|PICAMSDEV\Projects\Quincy\QTest\test cpp 
ft est cpp é 


j#include Cimstceaa. Es ce etree ate 
|#include “test .h” 


“Hello. world\n"; 
cout << foot); 
return 0 : 


editor documents, Figure 1: Quincy 96's application window. 


type into them, cut, 

copy, paste, and even pretend you are 
opening existing documents and saving 
ones you have changed. All the code to 
do that is generated for you by the De- 
veloper Studio. Easy. The hard part is do- 
ing more than that. 


Editor Font and Tab Stops 
The default font for CEditView objects is 
the system font, which, being proportion- 


ally spaced, is not particularly acceptable 
for typing source code. A fixed-spaced font 
is necessary so that code indentations line 
up properly. You can add a CFontDialog 
dialog box to your user interface and let 
the user select a font, but I prefer to have 
the code font of my choice, 10-point Couri- 
er, as the default for text-editor documents. 

The character font is associated with the 
document’s view. To associate a specific 
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font with a particular view, you first gen- 
erate the font as a data variable by in- 
stantiating an object of type CFont. De- 
clare this object as a data member of the 
derived CEditView class (see Listing One, 
listings begin on page 127) and create the 
font itself in the class constructor by call- 
ing the CFont class’s CreateFont member 
fuwnction, see Listing Two. Finally, apply 
the SetFont member function in the class’s 
overriding Create function after calling the 
base class’s overridden Create function 
(Listing Three). This action applies the cre- 
ated font to each open document of that 
type in the application. 

The arguments to CFont::CreateFont are 
not intuitive. I deduced their values by 
writing a program that uses CFontDialog 
to create fonts and then looking at the 
Courier font’s corresponding values. This 
pattern, then, explains only how to asso- 
ciate a 10-point Courier font with a de- 
rived CEditView class object. You would 
have to figure out the arguments to use 
the pattern for other fonts. 

Observe that the program also calls the 
SetTabStops function from the Create func- 
tion in Listing Three. I don’t like the de- 
fault eight-character tabs; they’re too wide. 
The function’s argument is expressed in 
dialog units, which are 1/4 of a character 
width, so 16 dialog units add up to one 
tab stop every four characters. 

This pattern is not particularly tricky. 
All the functions are well documented, ex- 
cept for the esoteric CreateFont arguments. 
The real problem was that nothing at the 
highest level pointed me to the functions 
or told me where to apply them and in 
what sequence. You must already know 
about them in order to go directly to their 
documentation. 


Line and Column Numbers 

Most text editors can optionally display 
the current line and column number. Word 
for Windows displays them in the status 
bar along with the time of day, page num- 
ber, and other stuff. The line number is 
essential information in a programmer’s 
editor because compilers report warnings 
and errors by line number. The CEditView 
class does not automatically display the 
line and column numbers. 

First, you have to extract the current 
line and column number from the current 
document. That sounds simple enough, 
but try to find out how from the docu- 
mentation when you don’t already know. 
Searches through the indexes and the on- 
line help for references to “line,” “col- 
umn,” “cursor,” and the like yield noth- 
ing. It takes a while to figure out that 
what we always called a “cursor” is now 
called a “caret.” 

The MFC online-help system is great. 
You can cruise through class descriptions 
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and find out all kinds of good stuff. After 
a thorough reading of the class-member 
descriptions for the CEditView class, its 
embedded CEdit class, and all its base 
classes through CView up to CWnd, I 
eventually found a way to get the current 
line and column number. 

The line number is easy. The CEdit::Line 
Index function returns the character po- 
sition of the first character of the current 
line when its argument is -1. That value 
can be converted into the current line 
number by passing it as an argument to 
the CEdit::LineFromChar function. 


GNU C++ 2.7.1 
implements many of 
the new ANSI 
constructs 





The column number is more difficult. 
The trick is to use the CEdit::GetSel func- 
tion to get the character positions of the 
beginning and ending of the CEdit object’s 
current selection, which is the currently 
marked block of text. As it turns out, when 
there is no currently marked block, the 
current selection is defined as beginning 
and ending at the current caret character 
position. When there is a marked block, 
the ending position corresponds to the 
current caret position. The documentation 
does not explain this behavior, but it 
works nonetheless. 

You would think that the difference 
between the current caret character po- 
sition and the character position of the 
first character of the line would produce 
the current column number. It does not, 
however, when tab characters are in the 
line, which is likely to happen in source 
code. The program has to scan the text 
of the current line and count the space 
characters that the view adds when it dis- 
plays tab-character offsets. You'll see that 
after 200 characters of text in a line, I 
don’t bother correcting for tabs. A C++ 
source-code line is too long if it needs 
200 characters. 

Listing Four is the function that deter- 
mines the current line and column num- 
ber from a CEditView class and sends 
those values to the derived CWinApp class 
to display in the status bar. 


There might be an easier way. There 
should be. I didn’t find it, however, and 
I’m sure if one exists, I’ll get lots of mail 
from veteran MFC programmers telling 
me about it and about how stupid I am 
for not already knowing about it. Where 
was all that help when I was trying to get 
this thing to work? One thing is certain. 
The CEdit class should offer up these data 
values more willingly. Deriving from CEd- 
it to add the behavior wouldn’t work be- 
cause then you’d have to coerce CEd- 
itView into using your derived class 
instead of CEdit. 

Having figured out the line and column 
values, the application has to display the 
data on the status bar. The standard VC++ 
status bar includes three little recessed 
boxes that tell you whether the Num 
Lock, Scroll Lock, and Caps Lock keys are 
on or off. This is a software concession 
to the knowledge that the lights on the 
keyboard that provide the same infor- 
mation get reversed sometimes. I wanted 
to add a box to the left of the standard 
ones to display the line and column num- 
bers. At the same time I wanted to get rid 
of the Scroll Lock box. (Does anyone 
know what the Scroll Lock key is for? 
Windows 95 sure doesn’t use it to lock 
out any scrolling. As far as I know its only 
purpose is to change the pilot’s viewing 
angle in Flight Simulator.) The status bar 
in Figure 1 shows that I got it working 
okay. Here’s how. 

Listing Five shows an array, indicators, 
that VC++ builds into the CMainFrame 
source-code file. indicators contains string 
identifiers. Listing Six shows the string- 
identifier declarations in the .rc resource 
text file. These strings identify the default 
text values for the panes in the status bar. 
The indicator elements tell the frame 
window how many panes there are and 
how wide they should be. The first indi- 
cator, ID_SEPARATOR, identifies the left- 
most, unrecessed pane that the system 
uses to display menu and tool-button help 
messages. 

Listing Seven shows the indicators ar- 
ray as modified to eliminate the Scroll Lock 
pane and insert a pane to use for the line 
and column numbers. I tried to use a dif- 
ferent string identifier created specifically 
for this purpose but couldn’t get it to work. 
This might be due to the beta copy of 
VC++ 4.0 that I have. 

Listing Eight shows code added to the 
CMainFrame::OnCreate function to change 
the characteristics of the new pane so that 
it is wider (120 pixels wide) and has no 
initial text value. 

Finally, Listings Nine and Ten show 
functions added to the main frame and 
application classes to display data in 
the new pane while the program is 
running. 
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Text-Data Serialization 

MFC includes a data-serialization feature for 
reading and writing documents. You pro- 
vide a Serialize function in the derived doc- 
ument class, and the system calls it to read 
and write document data with the appro- 
priate file opened and a CArchive object 
that knows how to store and retrieve ob- 
jects of many different types and classes. 

Normally the document class manages 
the document’s data, and the view class 
manages the display of the data. The text- 
editor view has to keep a complete copy 
of the text, so it might as well manage the 
data all by itself. 

The CEditView class embeds a CEdit 
object to contain the data. The CEdit class 
represents the data as an object of type 
CString, VC++’s string class. If you use the 
CArchive object to write and read the text, 
an object-description field is inserted at 
the beginning of the object. This works 
fine for text editing, but when you want 
to pass that file to a compiler or any other 
program that expects raw text, the object- 
description field gets in the way. 

The CEditView class includes a Serialize- 
Raw function that reads and writes text 
data without the object-description field. 
Listing Eleven shows how I used that func- 


= 


nd River Software 


tion from within the derived document 
class’s overriding Serialize function. The 
text document has only one view. The 
GetFirstViewPosition function returns a po- 
sition index to that one view that the sin- 
gle call to GetNextView uses to return a 
pointer to the CEditView object associat- 
ed with the document. A call to Serialize- 
Raw through that pointer passing a refer- 
ence to the CArchive object takes care of 
both reading and writing. The call to 
CArchive::Flush for output operations en- 
sures that the text is written to the file be- 
fore Quincy 96 tries to pass the file speci- 
fication to the compiler. 


Text Search and Replace 

The MFC documentation is vague on how 
to implement text search-and-replace op- 
erations in a CEditView derived class. As 
you read the class-member descriptions 
and meander through the hypertext links 
in the online help, you get the impression 
that MFC provides the primitives, and you 
have to integrate them somehow. Actual- 
ly, the process is much simpler. All you 
have to do is add menu commands with 
the ID_EDIT_FIND and ID_EDIT_RE- 
PLACE identifiers, and the framework does 
the rest. 
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Suppressing the GNU Document 

When you execute an MFC application 
built by the Developer Studio’s AppWiz- 
ard, the application’s first action is to cre- 
ate a new, empty document. If your ap- 
plication supports multiple document 
types, you must select one of them from 
a dialog box to tell the framework what 
kind of new document to create. That be- 
havior, which reflects the behavior of many 
Microsoft applications (Word, for exam- 
ple), is not always what you want. In 
Quincy’s case, the application should re- 
open the project and text documents that 
were open when the application last ran, 
similar to how the Developer Studio 
works. Getting an application to load pre- 
vious documents is no trick. Suppressing 
the creation of that initial new document 
is not as easy. 

Listing Twelve shows the code gener- 
ated in the derived CWinApp application 
class’s InitInstance member function. The 
CWinApp::ProcessShellCommand function 
opens documents specified on the com- 
mand line or dragged to the applications 
icon by the user. If neither condition ex- 
ists, the function creates a new document. 
That’s not what I want. If neither condi- 
tion exists, I want the application to use 
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values saved in its .ini file to load the doc- 
uments from the previous run. By step- 
ping into the ProcessShellCommand func- 
tion with the debugger, I was able to 
develop the test in Listing Thirteen, which 
calls ProcessShellCommand only when 
documents specifications are provided as 
command parameters from the command 
line or a drag operation. 


No GNUs is Good GNUs 

Enough of the GNU puns already. As you 
can probably tell, I am a fan of the GNU 
compiler suite. First, GNU is free; it offers 
schools and students a way to use and 
learn C and C++ without straining their 
budgets for individual compiler purchas- 
es and site licenses. Second, GNU’s C++ 
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language implementation is contemporary; 
it implements many of the new ANSI fea- 
tures that teachers should be teaching and 
students should be learning. 

So why, then, am I not using GNU com- 
pilers as the development platform for my 
“C Programming” column projects? 

I would have used GNU C++ rather 
than Visual C++ to build Quincy but for 
these reasons: First, the beta of the Cygnus 
port is not ready to compile C++ Windows 
programs. A small C demo works, but the 
C++ compiler chokes on some of the dec- 
larations in the Windows header files. Sec- 
ond, no one has licensed or ported MFC 
to GNU C++. That could happen only with 
Microsoft's blessing. Third, the Visual C++ 
Developer Studio, my development envi- 
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ronment of choice, launches the Microsoft 
compiler and does not work with GNU 
C++. If the first two problems are ever 
solved, I might try trussing up Quincy 96 
(97, 98, 99, ought-ought?) so that it takes 
on some of the visual aspects of App- 
Wizard and ClassWizard. 

Finally, the terms of the GNU Library 
General Public License for programs linked 
with GNU libraries would wrap the pro- 
gram in a shroud of source-code avail- 
ability responsibilities that I do not have 
time for. The source code to my projects 
is always available to everyone, but the 
GNU license binds you in perpetuity (or 
for three years after your last distribution, 
whichever comes first) to make available 
the source code to the GNU libraries, too, 
with everything offered on “a medium cus- 
tomarily used for software interchange,” 
as interpreted by the foundation but not 
defined in the license. Referring the user 
to a third-party source, even to the FSF 
themselves, is not an approved medium, 
although I don’t understand why. Neither 
is making the source code available for 
download from an online service or an In- 
ternet ftp site. I was told that the latter 
suggestion could not be approved because 
it would exclude anyone who does not 
have online access. 

I will be including all the Quincy source 
on the CD-ROM as well as the complete 
compiler package, but I don’t want to tie 
that particular product to programming 
projects in this column, and DD/ might 
not want to be required to sell the prod- 
uct for what the license calls “...a charge 
no more than the cost of performing this 
distribution,” upon which the GNU license 
does not elaborate. And so for now, I'll 
plod along with Borland and Visual C++. 


Source Code 

The source-code files for the Quincy 96 
project are free. You can download them 
from the DDJ Forum on CompuServe and 
on the Internet by anonymous ftp; see 
“Availability,” page 3. To run Quincy, you'll 
need the GNU Win32 executables from 
the Cygnus port. They can be found on 
ftp.cygnus/pub/sac. 

If you cannot get to one of the online 
sources, send a 3.5-inch high-density 
diskette and an addressed, stamped mail- 
er to me at Dr. Dobb’s Journal, 411 Borel 
Avenue, San Mateo, CA 94402, and I'll 
send you the Quincy source code (not the 
GNU stuff, however— it’s too big). Make 
sure that you include a note that says 
which project you want. The code is free, 
but if you care to support my Careware 
charity, include a dollar for the Brevard 
County Food Bank. 


DDJ 
(Listings begin on page 127.) 
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C PROGRAMMING 


Listing One 


class CTextView : public CEditView 
{ 


CFont newfont; 


—_ 
-. 


e e 
Listing Two 
CTextView: : CTextView() 
{ 
newfont.CreateFont (-13,0,08,0,400,0,0,0,0,1,2,1,49,"Courier") ; 


} 


Listing Three 


BOOL CTextView::Create(LPCTSTR lpszClassName,LPCTSTR 1lpszWindowName, 
DWORD dwStyle, const RECT& rect, 
CWnd* pParentWnd, UINT nID, CCreateContext* pContext) 


ao 


BOOL rtn = CWnd::Create(lpszClassName, lpszWindowName, dwStyle, 
rect, pParentWnd, nID, pContext); 

SetTabStops (16) ; 

SetFont (&newfont, TRUE) ; 

return rtn; 


eS 


Listing Four 


void CTextView: : ShowLineColumn () 
{ 
CEdit& rEdit = GetEditCtrl(); 
// --- character index of ist char, current line 
int nLineIndex = rEdit.LineIndex(-1) ; 
// --- current line number 
int nLineno = rEdit.LineFromChar (nLineIndex) ; 
// --- character index of current position 
int nStartChar, nEndChar; 
rEdit.GetSel(nStartChar, nEndChar ); 
// --- read the current line 
char buf [200] ; 
rEdit.GetLine(nLineno, buf, 200); 
// --- compute tab character adjustment 
int col = @; 
int tabct = @; 
for (int x = @; x < nEndChar - nLineIndex; x+t+) { 


if (x == 200) 
break; 
if (buf[x] == '\t') 
while (+tcol % 4) 
tabcttt+; 
else 
colt+; 
} 
// --- current column number 


int nColumn = (nEndChar - nLineIndex) + tabct; 
theApp. ShowLineColumn(nLinenot+1, nColumn+1) ; 


—_ 


Listing Five 


static UINT indicators[] = 
{ 

ID_SEPARATOR, 
ID_INDICATOR_CAPS, 
ID_INDICATOR_NUM, 
ID_INDICATOR_SCRL, 


3 

e e e 

Listing Six 

STRINGTABLE DISCARDABLE 

BEGIN 
ID_INDICATOR_EXT "EXT" 
ID_INDICATOR_CAPS "CAP" 
ID_INDICATOR_NUM "NUM" 
ID_INDICATOR_SCRL "SCRL" 
ID_INDICATOR_OVR "OVR" 
ID_INDICATOR_REC "REC" 

END 

e e 

Listing Seven 

static UINT indicators[] = 

{ 
ID_SEPARATOR, 


ID_INDICATOR_EXT, 
ID_INDICATOR_CAPS, 
ID_INDICATOR_NUM, 
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Listing Eight 


int CMainFrame: :OnCreate(LPCREATESTRUCT lpCreateStruct) 

{ 
TF ash 
m_wndStatusBar.SetPaneInfo(1, ID_INDICATOR_EXT, @, 120); 
m_wndStatusBar.SetPaneText(1, ""); 

} 


Listing Nine 


void CMainFrame: :ShowStatus(CString& strNewStatus, CString* pstrStatus) 
{ 
if (pstrStatus != 9) 
m_wndStatusBar.GetPaneText(1, *pstrStatus) ; 
m_wndStatusBar.SetPaneText(1, strNewStatus) ; 
m_wndStatusBar .SendMessage (WM_PAINT,@,9) ; 
} 


Listing Ten 


void CQuincyApp: :ShowStatusText (CString& strText, CString* pstrOldText) 
{ 
CMainFrame* pMainFrame = static_cast<CMainFrame*> (m_pMainWnd) ; 
pMainFrame->ShowStatus(strText, pstrOldText) ; 
} 
void CQuincyApp: :ShowLineColumn(int nLine, int nColumn) 
{ 
CString strExt; 
if (nLine != @) 
strExt.Format("Ln %d, Col %d", nLine, nColumn) ; 
ShowStatusText (strExt) ; 
} 


Listing Eleven 


void CTextDocument: :Serialize(CArchive& ar) 
{ 
POSITION pos = GetFirstViewPosition() ; 
ASSERT(pos != NULL); 
CEditView* pView = static_cast<CEditView*> (GetNextView(pos) ) ; 
ASSERT (pView != NULL); 


pView->SerializeRaw(ar) ; 
if (ar. IsStoring()) 
ar.Flush() ; 


Listing Twelve 


// Dispatch commands specified on the command line 
if (!ProcessShellCommand (cmdInfo) ) 
return FALSE; 


Listing Thirteen 


// --- suppress initial FileNew command on startup 
if (cmdInfo.m_nShellCommand != CCommandLineInfo::FileNew) { 
// Dispatch commands specified on the command line 
if (!ProcessShellCommand (cmdInfo) ) 
return FALSE; 


/[ ----- reload documents from the previous session 


DDJ 
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CIRCLE NO.600 ON READER SERVICE CARD 


Display custom graphics, titles, messages, and prompts. 

User selectable file groups—allow partial or file subset installations. 
Support password authorization. 

Include automatic uninstall capability. 

Request any type of user input—name, serial number, etc. 

Test for CPU, OS, video, memory, and/or disk space. 

Control installation based on user input or system configuration. 
Modify AUTOEXEC, CONFIG and INI or any other text files. 
Create or modify Windows groups and icons. 

Search for files and for text within files—great for upgrades. 


Install to or from multiple directories—ideal for CD-ROMs or networks. 


Update registry and process long file names (Win 95/NT version). 
Launch multiple applications after installation. 

Customize all system messages for non-English installations. 
PC-Shrink™ file compressor with file splitting. 

Check .DLL and .VBX file versions. 
Royalty-free distribution license. 
30-day money-back guarantee. 
Unlimited free technical support. 


PC-Install for DOS 


PC-Install for Win 95/NT 


CompuServe™: 74774,222 or GO TWENTY * Internet: info@twenty.com or http://www.twenty.com/~twenty 








Version 4 for 
MOS & Windows 


PC-Install for Windows 3.x ....... $179 


CD-ROMs 


Games for Daze 2 CD Set!............ we. 
Hundreds of games & demos ready to Plug & Play! Plus the 
X2FTP Game Programming Archive 


World Wide Catalog CD-ROM...................... 
See the World Wide Web without being on-line! 


Internet Tools CD-ROM............................ 
Networking tools & utils for DOS & UNIX 


CICA Windows 4 CD Set!....... i, 
Hundreds of Windows programs ready to plug & play! 


USENET 2CD Set! cece 
comp.sources & alt.sources groups + lots of FAQ’s 


Linux Developer’s Resource 4 CD Set! ........... 
Complete OS, Source Code, Slackware & more! 


Moo-Tiff CD-ROM for Linux........................ 
Complete development sys, 100% OSF/Motif-compatible 


Source Code CD-ROM .........................005. 
4.4-BSD-Lite, X11R6, MACH, Andrew Windowing 


POU ey Oe si boc sn dnp iehenkontnsundeseiyatesates 
Hundreds of Perl programs, scripts & utilities 


Standards CD-ROM ................. 0... cece ceca 
RFC’s, IEN’s, ITU Bluebook, Windows Sockets 


BSDisc CD-ROM (NetBSD & FreeBSD)............ 
Ready to use formats with install scripts * 


Call, Fax or send e-mail MC, VISA & AMEX accepted 
‘add shipping & handling: $5/US-Can-Mex $10/International 


P.O. Box 30370 
Flagstaff, AZ 86003-0370 \ | /L 1-800-800-6613 
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CIRCLE NO. 601 ON READER SERVICE CARD 


C-Install 


VERSION 4 


The award-winning, easy-to-use 
installation program for anyone who 
distributes applications or data files. 
With PC-Install, create a professional 
installation in less than 30 minutes. 


For more information,call 


800-735-2020 


20/20 Software, Inc. 
8196 SW Hall Blvd., Suite 200 


Beaverton, OR 97008 OO 


“a = 503-520-0504 Tel » 503-520-9118 Fax SOFTWARE 
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Does your computer really 


know what time it is? 


Many applications use the ..:**DOS and OS/2. CHRONOS 
time and date but the clocks.':will benefit any application 
in PCs are notoriously nd :.; using the time or date. End 
inaccurate! CHRONOS. :::***User licenses start at only 
offers clock managements $79.00. 

capability. You not; only set : 

the time to millisecond =”. 
accuracy but can specify . 
how accurate you want the 
clock toremain. © _ CHRON OS with your 
CHRONOS is available for. - application. 
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CIRCLE NO. 603 ON READER SERVICE CARD 


Y Redistribution and OEM 
7 licenses | are available to 


Hipparchus™ GIS Enabling Technology 


Over 250 functions provide C developers with breakthrough 

GIS capabilities. Interface with any GUI and any DBMS. Ellipsoidal 
vector algebra enables seamless 

global coverage, lightning-fast 

spatial indexing, polygon overlay 

and more! 


DOS/Windows Libraries, Application 
Prototyper, Tutorial (270 pp), 
Reference (340 pp): $475. Most 
other platforms supported 


Geodyssey Limited 

500, 815 Eighth Avenue SW, 

Calgary, Alberta, Canada T2P 3P2 
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CIRCLE NO. 604 ON READER SERVICE CARD 


Order your evaluation kit now: 800-986-6578 


Y WIBU-KEY — Secure against "crackers"! We are 

VY WIBU®-BOX for LPT, COM, ADB, as card = !00king for 
for (E)ISA slots and as PCMCIA-Card international 

V Protection for DOS, Windows and oeeeee 
networks without requiring source code modification 


Y Win32s, Windows NT, Mac’ OS, OS/2®, DOS 


WIBU-SYSTEMS GmbH 
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CIRCLE NO.605 ON READER SERVICE CARD 


Need Precision Timing Tools For 
Windows 3.x, 95, and NT? 


Announcing ExacTicks, Ryle Design's new precision 

¥ timing toolkit for 16 and Se bit x86 Windows 

B\ developers. A single C++ and Delphi Object Pascal 
Mee; class library provides precision stopwatch timers, 
== delays, alarms, and event schedulers under all the 


Winds 16 and 22 bit variants. Complete source in both 


C++ and Delphi's Object Pascal is included. ExacTicks Is the 
definitive Windows timing library for execution profiling, data 
acquisition, and process control applications. For Visual C++, 
Borland C++, Watcom C++, and Delphi. US$129.95. 


Add $5 shipping USA, $10 elsewhere, VISA, MC, AMEX. 30 day “No Questions 
Asked” return policy. Specsheets on BBS or call/fax/email for full catalog. 


Ryle Design “Purveyors of Big Science Since 1987” 
PO Box 22, Mt. Pleasant, Michigan 48804 USA Voice/Fax: 517.773.0587 
BBS: 517.772.2393 CIS: 73047,1765 Internet: 73047.1765@compuserve.com 


CIRCLE NO. 606 ON READER SERVICE CARD 


Voice: (415) 655-4182 
Fax: (415) 358-9749 


Internet: ccanion@mfi.com 


Translate 
your old 
PASCAL or 
BASIC code 
(f into readable 
and maintainable 
C at up to 35000 
Act lines per minute. 


Vax Pascal =» C 
Turbo Pascal =» C 
Microsoft Pascal => C 
Microsoft GW-Basic => C 
Microsoft Quick Basic =» C 
Microsoft Professional Basic =» C 
" Turbo Pascal with Objects => C++ 


Provantage 
7249 Whipple Avenue NW 
North Canton OH 44720 
‘Phone: 216-494-3781 
Fax: 216-494-5260 


All Trade Marks acknowledged 


Technosoft (Europe) 
Enterprise House 
Cherry Orchard Lane 
Salisbury SP2 7LD, UK 
’Phone: +44-722-414201 
Fax: +44-794-884087 


CIRCLE NO. 607 ON READER SERVICE CARD 














Basic Scripting 
16 & 32 bit Royalty Free 







No nonsense royalty-free licensing 
30 Day money back guarantee 

VBA Compatible 
OLE Automation — 
Dialog Editor la 
Extendible Syntax | 
Debugger 

16 & 32 Bit in Box 
Source Code Available 


Dynamic Dialogs 






















































HASSLE-FREE HARDWA 
A J oan Pe 


REAL TIME TOOLKIT FO 


“source cope> N 


Spend your time writing your App... not wading through D.D.K. documentation! 
Fast hardware control under Win32® without the DEVICE DRIVER KIT! 


¥PORTI/O JMEMORYI/O ¥ INTERUPTS 


Also available on: Alpha™, PowerPC™, MIPS™ versions. 


1-800-962-2114 OFFICE (206) 771-3610 FAX (206) 771-2742 :- 
we NO RUNTIME ROYALTIES 
“Visa, MC, Amex, Approved P.P.* 


. Monstra, 
ti 

WOrdE. Inger oc fault Word.Basiey”® Automatic Dre 

Convers; 

on 


B CALLTODAY! |, . [ee~ 
§ 1(800)790-4050 



















































Call for a free whitepaper 
phone: 602-922-4883 
fax: 602-951-8047 
CompuServe: 70444,165 
cypress@cypressinc.com 
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How to stay ahead of the 
market and the psychiatrist. 





A 








The Serial Communication Libraries, DLLs, & Tools 
You Will Ever Need For Windows 3.x, 


, and MS-DOS. Accept No Less Than The Best. 






Searching for a cost-effective way to create focused software for 
a specific market? License Autodesk® OEM Technology. That 
way, you can relieve the stress of writing industry-compatible 
code and instead, focus on your customers and expanding your 
market. Plus, the Autodesk name carries worldwide recognition, 
a strong three-million customer base and reputation for success. 
All elements that should keep the psychiatrist far away. 



















@ Unlimited number of ports active concurrently. ® Hardware/Software Flow Control. 

® 8250/16450/16550 Auto detection/Up to 115200 baud. ® Product Customization. 

® 100% Port re-entrant code(Important for multitasking). @ Remap/Change baud rates/divisor. 

® Support most intelligent/all dumb multiport cards(Arnet, Digiboard, Boca, GTEK , AST, & more). 






















Professional Serial I/O Libraries & DLLs for 
Windows 3.x, Windows 95, NT, & MSDOS 





Ultra High Speed Serial I/O VxD For Windows 


































































SALE: larguagse. soles Ge appticatiood ea cal cath Oo ee eae rt ates ne te SHIREY License any of the following Autodesk OEM Engines: 
Supports languages, tools, or applications that can call P : ae : 
® the Windows API ye < ahich @ MS-DOS high speed libraries for calling VxDs from a DOS box. 
@® Complete source code to all libraries & DLLs. . ees a ol gente in a he 32 bit a 
utomatic detection o h s/Uses transmit & receive S. 
S API for Windows 3x, , NT, & MS-DOS. . 
= — piieertt . Ma te @ May be called from Windows & MS-DOS concurrently. 
@ High level Hayes compatible modem functions. ® Baud rates in excess of 115.2K underWindows!!! DWG fe) = MM 
® X, Y, Zmodem file transfers on multiple ports © Integrates seamlessly with all COMM-DRV products. 
Asynchronous & timed callback to user functions on (Q) 
© different serial communication events(modem signals, 7 N i cel OFAN BD) : @) E | 
buffer counts, character reception, and more). 
Supports Visual C/C++, ANSI C/C++, QuickBasic, Visual ’ te ne Weie Pe oe Med 
© Basic (MSDOS & Windows), Assembly, Access, etc. MS-DOS Serial I/O TSRs & Utilities eAutoVision OEM a 
Transmit data from user callback on any event(important for @ True DOS device driver that allows serial ports to be opened like files ¥ 
mutirop applications). under MS-DOS &e Windows *AutoCAD Data Extension OEM 
@ Extensive scanning of input character stream. ® Provides FOSSIL interface for all supported cards(BBS operators). } a 
® Provides Int14h, Int21h, & DAM interfaces. (2) Le 
: : e da 
wesc Price List ® Compatible with Desqview and Windows. H ete) PS OE M A f i 7 
® Real time serial port monitoring to screen and disk. a i Hh i: 
COMM-DRV/VxD (Introductory Offer)...$ 99.95 |/® Mini-BBS for file transfer/Spawnable standalone file transfer engine. 
COMME-DRV/DOS.. ccc cccccccccccccccces $ 99.95 
COMM DIY (WA 50's dicicisicicicie cielcleicleleleicielele $ 99.95 
Port Card (16450). .cscvcccvcccccces $110.00 
4Poxrt Card (16550)... .ccccccccccccce $170.00 Wi : 1s . A ° ° 
indows Replacement Serial Co e Iriv 
Wack CHE (16ER0I CS an Mies ise dows Replacement Serial Communication Driver HIN U O eC S - 
8Port Multiport Card(16550)........ $225.00 : ae ; 3 ‘ 
; ‘ True Windows communication device replacement. Use your favorite 
Software Combo(Lib,VxD, Dos, Win)..$399.95 Windows communication applications on all multiport cards we support. 
Complete Combo (Sftwe+4Port (16550) ..$499.95 
Allow the use of more than 9 serial ports under Windows by allowin 
BBS SYSOP Combo(Dos+4Port/16550)...$199.95 P Peas 8 
se ier eR Call 1-800-964-6432 and ask for InfoPak 1950 
= = = t 















email: oem_info@autodesk.com 






2470 S Dairy Ashford Suite 188, Houston, TX 77077 










thie 
Bait 
HAA 










713-568-3334 713-568-6401 © 1996 Autodesk, Inc. Autodesk, the Autodesk logo, AutoCAD, and ADE are a 
sales @ wescnet.com registered trademarks, and AutoVision and HOOPS are trademarks of ie 





Visa/Mastercard/Discover/AMEX/Checks/Approved P.O. 


http://www.wcscnet.com/home.htm Autodesk, Inc. in the U.S. and other countries. 
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Pentium® Optimizer 


PentOpt Professional automatically flow charts and annotates : 
your assembly source with Pentium optimization information § 


(pipeline pairing, AGI’s and more). Reports statistics by loop 
nesting depth. (6199 95) ASMFLOW generates flow charts, tree 
diagrams, register usage analysis, x-ref, timing info and more. 
Available for 80x86, 8051, 8085, Z-80, 68HC11 and 1750A. 
($199.95) Call for free demo and catalog of assembly, TSR and 
floating point libraries. ($99.95 to $299.95) 


Pentium is a registered trademark of Intel 


Quantasm Corp. 
19672 Stevens Creek Blvd #307-D 
Cupertino, CA 95014 
800-765-8086 or 408-244-6826 
FAX: 408-244-7268 
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ITU-T (CCITT) COMPRESSION 
Compress Audio and Speech up to 8 to 1 


USES: ¢ computer telephony « voice mail 
emultimedia audio «LAN telephony 


 G.711 p-law & A-law Compression/Expansion 

¢ G.722 7kHz Audio in 64kbs (sub-banded ADPCM) 

¢ G.726 40,32,24,16kbs ADPCM 

° G.727 5-,4-,3-,2-bit Sample Embedded ADPCM 

¢ G.728 16kbs Code Excited Linear Prediction (CELP) 


Get all five in |DOS 199 
one package | UNIX or Windows oe 


Works with y-law, A-law and sound card PCM! 


LANGUAGE and AUDITORY SYSTEMS, Inc. (203) 786-5430 
25 Sdence Park, New Haven CT 0651 1+ Fax (203) 786-5431 
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THE REVOLUTIONARY GUIDE TO 
VISUAL BASIC 4 


_ eVB developers reference to creating large 
scale commercial applications 
eDetailed coverage : the professional toolkit 
eCovers Windows and VB interaction; 
- including API and OLE 
~~ Larry Roof ISBN 10-874416-370 $44.95 


T WROX PRESS 







CC-RIDER 
VISUALIZE YOUR C/C++ CODE 


Browsing 
Editing 
Documentation 


Western 


(970) 327-4898 


http://www.westernwares.com/ccrider 


mimrirwun FrAnR ALL Nnranrn crovuirr CSADH 





TO ORDER 
Tel.800 937 5557¢Fax 800 PRI ORDER} 
VISA MASTERCARD AMEX DISCOVER =f 
QUOTE CODE CL21 FOR FREE FREIGHT 


ar eecaacel” 600 614 4577 im 
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M++ Version 5.1 
Complete C++ Math Library 
eLINPACK and EISPACK classes 
*Complete signal processing suite 
*Multidimensional array language with 
generalized inner and outer operations 
Persistent arrays 
*Extensive set of mathematical functions 
«Advanced functionality provided by optional 


modules 
Dyad Software Corporation 
6947 Coal Creek Pkwy SE #361, Newcastle WA 98059 
206-637-9426 


CIRCLE NO. 504 ON READER SERVICE CARD 


CDROMs! 


Official Slackware™ Linux — Slackware 3.0 (ELF) Linux, by author of 
Slackware. Easy install: learn Unix. XFree86 3.1.2, Tcl/Tk, GCC 
(2.7.0) compiler, Doom™. Works on 98% of PC's. 2 discs $39.95 
Slackware subscription — convenient 3 month updates $24.95 

FreeBSD™ 2.0.5 — Berkeley BSD for PC. Solid Unix, full src, XFree86 
3.1.1, dev. tools, etc. (Subscription every 6 mo. $24.95) $39.95 

POV-Ray — 3-D Raytracing: 1000 wow! images, src/binaries $39.95 

Avalon — 3D objects, graphics source, libraries, info. $39.95 

C Users Group Library — C Users’ Journal src code, listings $49.95 

CICA MS Windows — very popular. 5000 up—to—date shareware. 
2 discs. Subscription each 3 months $19.95 issue. $29.95" 

Hobbes OS/2 Archived — 05/2 Mag 1994 Ed's choice. 600MB 
selected OS/2 apps, drivers, docs. $19.95 3 mo. sub. 

Simtel MSDOS — Two disc set, classic MSDOS shareware $34.95" 

Science Library — Technical, engineering shareware + book $39.95" 

GNU — GNU distribution, src & compiled for Sun OS, Sol. 

Perl — Source, binaries for many systems, documents. $39.95 

TeX — Tex and LaTex. 1000 MB of code, binaries, docs. $39.95 


Ada — Two disc set, Programming tools Ada source code $39.95° 


Math Solutions — Math programs, source code, docs $39.95" 
Clipper — DB language source, utils, libraries & docs $39.95 
Music Workshop — Music demos, players, wavs. (Win) $39.95" 


internet Info — Thousands of computer and internet docs $39.95 § 


*Shareware programs require separate payment to authors if found useful 
— Authors wanted. Please email discdev@cdrom.com — 


ORDER NOW! 1-800-786-9907 


Shipping is $5 in USA/Canada/Mexico, $9 Overseas per order 
are | a 


eer 2 


Walnut Creek CDROM 


4041 Pike Lane, Suite D-393 Concord, CA 94520 
+1-510-674-0783 + FAX: +1-510-674-0821 + email: orders@cdrom.com 








All of our CDROMs are unconditionally guaranteed! [Adcode: 393 | 
| Call today for your free catalog of all our CDROM titles! NEO 298 
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UNIVERSAL CD-ROM 


WIN RTT (alm, 4m @7, Oo mm ©) -7/ | oA [al (-)aar-)er-lale melele|ce:-m @xele(=t~ 


fo)al Vans Ware tare mele} 


BEST PROGRAMMING SOURCE ON CD-ROM! 
FOR DR.DOBB’S JOURNAL READERS (code: DBW95) 
¢ All Walnut Creek CD-ROM 10% Off 
¢ All Infomagic CD-ROM 10% Off 
Numerous current programming CD-ROM available... 
Unix.Windows, NT, OS/2, DOS, Internet, WWW, HTML, TCP/IP, VR, 


3D, Mac, Mpeg, Motiff, X-Windows, BSD, C/C++, dBase, Dr. Dobb's 
Journal, Perl, GNU, Linux, Tex, Tcl/Tk, CICA, Standard, Al, NeXT, 
Ada, Clipper, and many more with source code! 


i 's: SHIP WORLDWIDE FROM 
Also 1500 various CD’s: MUG VALLEY 


; UNIVERSAL CD-ROM 
eGames/Entertainment 
*Education/References NF entrar CARO 520 Lawrence Exp. #307 
eSound/Video/Art ———_—sVISITOURINTERNETHOME Sunnyvale, CA 94086 
oe greranniat Engineering — PAGES FOR CURRENT USA 
Adult LIST AND PRICE 


Fax: 408999200457 
Email: ucr@ Kee ) mail.com 
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$29.95'} 


$39.95° | 











WEB WEAVER PLUS 
World Wide Web Page Design Tool Kit 


- Backgrounds - Textures - Icons - Bitmaps 
-Pictures - Sounds - Templates - Tools 
Everything you need to create dynamic homepages and HTML Hypertext- 
linked graphical documents. Sample HTML Templates, matched sets of back- 
grounds, textures, icons, and highlighter lines. Add interest to your Webpages 
with thousands of sound effects. Build your own HOTLIST of recommended 
sites from a database listing thousands of websites. Also included is Netcom’s 
acclaimed software package, NETCRUISER. No Start-up fee—save $25.00. 
More than 400+ hrs. per month FREE at no charge. Low monthly rate. 
$24.95, plus $5 S&H 


TO ORDER, OR RECEIVE OUR FREE CATALOG: 
800 78-CDROM Sada 872-7487 or FAX (916) 872-3826 
ttp:\\www.km-cd.com 
KNOWLEDGE MEDIA 


436 NUNNELEY RD., STE. B, PARADISE, CA 95969 
VISA, MASTER CARD accepted 
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Personal Communications Library Supports 20 ports to 115200 baud, 
protected mode, multiport dumb cards (Digiboard, BOCA), any IRQ & 
UART address, Interrupt driven, HW flow control, 16550 UART & modem 


AT command support. Source code included. Specify C/C++, Turbo 
Pascal, Visual BASIC, PowerBASIC (DOS), or C/C++ (Win).— $65 + s&h 





Personal Protocol Library DOS protocol libraries include ASCIl, 
XMODEM, YMODEM, and ZMODEM protocols with script compiler & 
interpreter. Specify C/C++, Turbo Pascal, or PowerBASIC. Requires 
communications library above. — $40 + s&h 


Includes manuals & one year support. Get FREE shareware version from 
our BBS (14.4 KB). FTP: ftp.traveller.com. Path: fpub/users/msc. 


Windows version reviewed in Windows/DOS Developers Journal (Mar 95). 


205-881-4630 Voice 
205-880-0925 FAX 
205-880-9748 BBS 


MarshallSoft Computing, Inc. 
PO Box 4543 Huntsville AL 35815 
[email: msc@traveller.com ] 
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New v3.12 High-performance, 


portable compression 
of buffers & files, 
archiving, disk 
spanning, full source 
code and more. 


DOS $249 
Windows $299 
Unix $349 


Free demo on BBS (606) 268-1251 


1-800-775-1073 


DC Micro Development, Lexington, KY USA 
Tel (606) 268-1559 Fax (606) 266-0726 
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The McCabe 00 ToolSet™ 


The McCabe Object-Oriented ToolSet™ is the newest addition to the 
McCabe ToolSet™. It provides a wide variety of system metrics and a clear 
visualization of OO applications architecture. C++ systems can be fully 
tested and SAFE and UNSAFE classes identified. To reduce redundancy, 
the tool finds reusable code throughout a system. In addition, it contains 


I features that help migrate systems from traditional languages to 00. The 


McCabe ToolSet is also available for over 25 traditional languages and 


dialects. 


Uncover Your Software ===mesMcCabe 
me Wa SaAssociates® 


For Further information Call 800-638-6316 or Fax 410-995-1528 
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IB - spelling * Custom - 


info@teratech.com _htto/Awww.tera 
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Viewing 


"View" Enable Your Application 


Introducing the most extensive viewing libraries -- 
Viewing & Conversion Enabling Technology 
(VCET™), an OEM product from C.S.1.. 

Add viewing capabilities for any format within 
your Windows application in a matter of hours! 


-VCET is the same technology used in AutoVue® 


and other leading viewing 
- management software. 


customer base." 


process." 


financial + * ProBas - & other 15 DOS libs 
B - telephony * VB training - 2 day intro class 
ASN, VB programming 


800-447-9120 ext.1173 


Dept 1173, 100 Park Avenue, Suite 360, Rockville MD 20850 
Intl:+1-301-424-3903 Fax:301-762-8185 BBS:301-762-8184 


POL COU ET att] 


"Intergraph uses C.S.I. technology in our DM/View and 
DM/Redline products. The products are well received with our 


Terry Lynch, Executive Director, Intergraph Corp. 


"We were easily able to integrate VCET into our software 
application. It was the simplest part of our development 


Mike Hunting, Project Manager, Kruse Inc. 


WEVELOFMENIT LOOLS 


Establish peer-to-peer 
transactions between 
DOS & Windows apps! 


WINGate’s 44-function API, DOS libraries and 
Windows DLL melds Windows and DOS into one 
application platform. 

Use WINGate to extend any DOS application with 
Windows functionality using private message or 
DDE transactions; and/or access DOS functions 
from any Windows application. 


Real-time, VxD-based 


Put a Windows interface 
on any DOS or host 
legacy application 
Use any Windows language to create Windows 
front-ends for your hardworking, dependable DOS 

or host applications. 

RobinHood’s 53 function API allows you to send 
keys, read screens, manage tasks like scheduling, 
priorities and window status, DOS output 
redirection, etc. 


Also, ask about RobinHood/VB, the VB code 
generator which produces legacy code frontends in 






minutes! es interprocess 
eo No moditication to communications 
. source code is required! technology. 
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difficult maintenance. Nobody’s idea of fun. 


charge and concentrate on the real problems. 


turning to AnaGram. Call for free trial copy. 
Anagram" by Parsifal Software 
P.O. Box 219, Wayland, MA 01778 

(800) 879- 2577 

CIS: 72603,1763 


and document 
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Dr. DeeBee” ODBC Tools 


Tools for ODBC development and support 








Office Documents: 


Quattro Pro, dBase, Paradox... 
Engineering Documents: 


CALS GP4, TIFF. Hybrid... 
Desktop Formats: 
PS, EPS, JPEG, GIF... 


E’c.S./. 


Cimmetry Systems Inc. 
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Write state-of-the art applications without learning 
C++ in a fraction of the code you use now. 


NT 3.x in a few lines. Write apps after one day! 


without the overhead. 


Instantly Support Over 150 File Formats! 


MS-Word, WordPerfect, AMIPRO, MS-Excel, Lotus 123, 


AutoCAD, MicroStation, CADKEY, HPGL, IGES, CGM, 






















AS") Ever wonder why your ODBC app 
oN is not working? Why it’s just too 
Slow? If the ODBC driver is OK? 
Dr. DeeBee utilities reveal the 
inner workings of ODBC. 


Call for a Free ODBC prescription! 
NEW! Build ODBC drivers fast with our ODBC Driver Kit 


617-497-1376 












| 


800-361-1904 
Tel (514) 735-3219 
Fax (514) 735-6440 
BBS (514) 735-3905 





—SVYVUALFE,.—_— 
PO. Box 91 Kendall, Cambridge, MA 02142 Fax 617-497-8729 
http: / /www.syware.com/drdeebee/ 
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B.S. & MLS. 


In Computer Science 
® ALL COURSES HOME STUDY 










-- 3.1, '95 and 


_- Smalltalk/CLOS ability in C_ | ® Approved for tuition reimbursement AMERIC AN 
by leading corporations INSTITUTE 
® Increase your earning power al 


, supports DOS, all Windows, Linux, Unix. 


Call 800-566-899 1 615-791-1636 () 


Algorithms Corporation 615-791-7736 (f) 
http://www.edge.net/algorithms 


dynace-info@edge.net 
















*C++, Using oe and Ada COMPUTER 
courses available 
© CareerPath training in computer SCIEN CIENCES 


programming available 
For free information call: 
1-800-767-AICS 


ACCREDITED MEMBER 
World Association of 
Universities and Colleges 
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REPORT WOES? 

















- Icons, bitmaps, long and short texts. 


- Fonts, word-wrapping, alignment. 





KWG Software 
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PrintF OrmM. to the rescue! 


Create complex an otherwise impossible reports. 
- Generate high quality documents with little effort. 
- Very well suited for typical database reports. 
- Foem letters, tables outlines, lists and envelopes. 


- DLL for all laguages, C++ interface, VisualBasic. 


- Headers and footers with page numbering. 
Search for PFO in CompuServe MSMFC or MSBASIC forums 
DLL 16-bit version just $140. Visa and AMEX cards welcome. 


CIS: 100010,204 
Tel: +49-531-72982 


SLOW, 
LARGE, 
IMPOSSIBLE? 





The Complete FORTRAN Programmer’s Toolki 


Create sophisticated state-of-the-art user interfaces for your FORTRAN 
programs. Spindrift’s callable subroutines and functions let you 
© Have data entry screens, dialog boxes, scrolling list boxes 
pull-down menus, push buttons, help panels, etc. All with full 
mouse support. 
© Much more! 281 subroutines and functions for keyboard, 
screen, mouse, DOS control, and hardware status. 
Comprehensive demonstration program shows what you can do and how to do it. 
Now shipping Version 3.0 with all new User Guide. 


PRICE: 16BitCompilers-$149 32 Bit Compilers - $289 


Spindrift Laboratories, Ltd. 
116 South Harvard Avenue ¢ Arlington Heights ¢ IL 60005 © USA 
Phone: (708) 255-6909 © FAX: (708) 255-6101 
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Fax: +49-531-74501 


SERVICE CARD 











































CAN PARSING BE FUN AND EASY? 


Parsing input used to mean tricky logic with lots 
of places for bugs to hide, slipped schedules, 


Now, AnaGram changes all that. You can take 
Expressions? Database queries? Scripts? A 


command language? No problem. It’s fun, it’s 
easy. See why developers the world over are 


Voice/Fax (508) 358-2564 
jholland @ world.std.com 


EDUCATION 


f. 


GRAFEFIC LIDNRARNIELCS 


VICTOR 
Image Processing Library 


Fast BMP, TIFF, PCX, GIF, TGA, JPEG. Adjust brightness, 
contrast, sharpen, create filters, resize, rotate, +more of 
single image, multiple images, or any image area; color 
reduction to optimum, specific, or std. palette; print; scan; 
crop, combine, compare, blend images. EGA, VGA, SVGA. 


DOS $199, 16-bit DLL $299, 32-bit DLL $499 


Catenary Systems 
314-962-7833/fax: 314-962-8037 


ask for free demo src avail visa/mc/c.o.d. 
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WINGRAF 2.0 | INGRAF 7.0 


(Win 3.1, Win95, WinNT) | (DOS/DOS extenders) 


WINGRAF & INGRAF are Graphics libraries for 
Scientific, Engineering and Business applications. 
Each library contains over 150 routines to on 
VIDEO, PRINTERS and PLOTTERS. 


C, PASCAL, DELPHI, BASIC, and FORTRAN 
versions. NO ROYALTIES, FULL SOURCE 


Sutrasoft P.o. Box 1733 
Sugar Land, TX 77487-1733 
TEL: (713) 491-2088 FAX: (713) 240-6883 
76163.1164@COMPUSERVE.COM 
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Data Compression 
Toolkits 





| DynaZIP 


The ROYALTY-FREE DynaZIP family of developer's tools let you 
read, test, create, write, and update industry standard ZIP 
files directly from your Windows-based products. No more 
"shelling" to DOS, and no more fussing with proprietary 
compression formats. Fast, easy to use, and totally reliable! 
Versions for C/C++, Pascal, VB, database, 16 and 32 bit. 


Fully supported, 30-day no-risk guarantee! 
Call today, toll free: (800) 962-2949 
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FAST - ROYALTY FREE - EASY TO INTEGRATE. 
Professional spelling and thesaurus development 
toolkit. Offers a comprehensive set of features to 
address language specific requirements. 

Spelling, plus one language $399, Thesaurus $399, 
Both $599, Language Packs $299. 

Available for DOS, WIN31, WIN 95, WIN NT and OS/2 


 Multi-lin ual: American, British, Danish, Dutch, French, Can. 
_ French, German, | , Norwegian, Spanish, Swedish. _ 




















LexSaurus Software, Inc. 
427-3 Amherst St. Suite 303, Nashua, NH 03063 
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Sentry Spelling-Checker Engine: Powerful, 
full-featured spelling-checker software 
that’s available as royalty-free portable 
ANSI-C source code or 16/32-bit Windows 
DLLs. Used in many popular commercial 
applications. 


Wintertree Software Onc. 
Phone: 613-825-6271 ¢ FAX: 613-825-5521 


wsi@fox.nstn.ca ® http://fox.nstn.ca/~wsi 
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LOCALIZATION 


Localize your Windows 
applications to Japanese 


¢ localize manuals and documents to Japanese 
¢ localize and build help files to Japanese 

| © localize and build source codes to Japanese 

| ¢ test applications on Japanese Windows 

| © market applications as your agency in Japan 


/PROSOFT™ Corporation 


| 4-11-110 Ueikeda. 2 chome, Ikeda-shi, Osaka, JAPAN 
| Phone: 81-727-536-097 Fax: 81-727-533-292 
| Internet: Prosoftx @ osk.threewebnet.or.jp 
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MARKETING 
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(510) 745-0146 


WGS Linux Pro 


You already know that Linux is one of the world’s 
most advanced, 32-bit Internet-ready, GUI, multi- 
media, multi-user, multi-tasking operating systems. 
But did you know that WGS Linux Pro is more 

complete, more stable and better supported than 
other Linux CDs? And it’s yours for just $69 - 
30% off the regular $99 price! Order today! 


al 
1a @/@m Vacs 


P.O. Box 460190 * Aurora, CO 80046-0190 
Tamm saa Tel: 303-699-7470 © Fax: 303-699-2793 
Internet Mail: info@wgs.com 


WorkGROUP 
http://www.wgs.com 


SOLUTIONS, INC. 
CIRCLE NO. 526 ON READER SERVICE CARD 
PROLOG 


Amzi!’Prolog+ 
Logic Server 
"Dynamic Duo" 

VB Tech Journal 


"Solid, commer- 


Delphi, VB \ cial grade...ideal 


for embedding" 
PC Al, Sep 95 

FREE CATALOG 
Amzi! «40 Samuel Prescott Dr 


Stow MA 01775 « 508.897.7332 
fax 897.2784 « info@amzi.com 
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ECURITY 


DDJ9602PAD 


Marx CryptoBox is the most sophisti- 

cated and effective protection against 

software piracy you can buy! 

Programmable microprocessor capabl 

of 1,000,000 read/write operations ¢ | 

codes are programmable without special equipment 

e Integration of sophisticated crypt algorithm ¢ Completely com- 
patible under DOS, WINDOWS or 0S/2 @ Perfect transparency 


Call 1-800-MARX INT 


\ ' for complete speci fications, or a low cost trial kit. 
Or write P.O. Box 95743, Atlanta, GA 30347 
INTERNATIONAL, INC. Germany: 08403 1555 France: 8881 4031 
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“Software Copy Protection with NO Hardware Key and NO Disk Key ” 


is a software copy protection that is 
completely secure from any disk copy program 
completely compatible with any MSDOS, MS WINDOWS, WIN95, WIN NT 
completely compatible with CD-ROM, BBS, or Internet distribution! 
customer friendly - no disk key, no hardware key, less support calls 


can increase your software sales by allowing you to sell your program 
by increments—sell add-on software options or levels to your customers 
by number of runs—e.g. sell 100 calculations for $100.00 
by time period—e.g. lease or demo your program for 60 days 


uses a numeric key that can be transmitted by phone, 
fax,or email. Sell your customers more options, more copies, more 
time or more runs instantly, just by making a telephone call pret 
for overseas customers or distributors). CrypKey is produced 
Kenonic Controls Ltd.—engineering and software since 1972 
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CPU-Lock « CD-ROM Lock e 
Serialization « Registration ¢ Network 
User Limits ¢ Date & Execution Limits 
e Windows 95 e 3.11 ¢ DOS 


Call Today For More Information! 
Phone: (816) 776-2700 ¢ Fax: (816) 776-8398 
E-Mail:aztech@tyrell.net 


European Software Support 


Selling in Europe? We specialize in 
software support and assistance. From 
one central location with high qualified 
personnel speaking four (4) languages 
(German, French, Italian, English). 
We guarantee to your customers full, high 
quality assistance and reduce your costs. 
Parsec System 


Via Trevano 7a * 6900 Lugano (Switzerland) 
phone:(+41) 91 921 30 29 « fax:(+41) 91 921 30 48 
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SORTING 


Opt-Tech Sort 


High Performance Sort/Merge/Select Utility. Run from the 
command line or Call as a subroutine to your programs. 
Supports most languages and file types. Unlimited file size, 
multiple keys and much more! New Version 5.0 includes 
More Speed and More Features! 


MS-DOS or Windows $149 — 0S/2 or Unix $249 


(702) 588-3737 


Opt-Tech Data Processing 
P.O. Box 678 « Zephyr Cove NV 89448 
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C and C++ DOCUMENTATION TOOLS (v. 6.0) 


Graphic-tree of caller/called function hierarchy, cross-reference, 
file/function index. 
Creates/inserts/updates comment-blocks (functions/identifiers 
used) for each function. 
Calculates path complexity, counts lines with comments, code, 
'C' statements. 
Lists and action-diagrams, or reformats source into user-selected 
standard formats. 
Creates cross-reference of local/global/define/parameter identifiers. 
All 5 programs integrated as DOS program. <10,000 
lines. V6.0 C-BROWSE Windows graphic-tree viewer. 
DOS, Windows, 0S/2. 3-ring binder/case. 
Processes 1,000,000+ lines. 


SOFTWARE BLACKSMITHS INC. 


6064 St Ives Way, Mississauga _— Voice/Fax 
ONT Canada L5N-4M1 http://swbs.idirect.com 
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DISTRIBUTED COMPILATION TOOL 


Especially efficient for large C/C+H/FORTRAN projects. 
Now you can speed up your compilation drastically 
without modifying your source code. No more 5 hour 
compiles. CPF intercepts calls to compiler made from 
your make files and distributes compilation over several 
LAN nodes and/or CPUs on multiple-processor systems. 
Your compilation must run under Windows 95/NT; cross 
compilers are supported. Currently works with Visual 
C++ 2.x, 4.0 and Watcom 10.5 desktops. Command-line 
C/C++ compilers from Microsoft, Borland and Watcom 
are supported also. Completely userconfigurable. 


Movil - PO.Box 391536 + Mountain View,CA 94039-1536 
Voice: (408) 773-0984 + Fax: (408) 773-9059 
Email: marksupp@movil.com 
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WEB tlB 


VBXs and DLLs for Netscape and 
Mosaic DDE APIs, HTTP and HTML. 
Specific support for VB, Delphi, 
C/C++, PowerBuilder and 
SQLWindows. 


Potomac Software 
http://potsoft.inter.net/potsoft/ 301-216-0604 
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ANA 


TrueType and Type 1 bar 
code fonts you can use 
within any Windows or 
Macintosh application. 
800 48-ASOFT 


206 932.6028 


Zalea 


software inc. 
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O d Wide Websites for 
ration oo the latest 
lopment tools and services. Will 
y find your site? Building enough 

awareness to increase traffic on your 
Web site is a challenge. 


There is a solution. 


Dr. Dobb’s Web Directory, a 
new advertising section geared 
exclusively towards the promotion of 
World Wide Web sites. 

DDJ’s World Wide Web 
Directory will list your organization's 
name and URL under one of 1|0 
categories. Over 1.5 million annual 
impressions for |/10¢ each 


CALL 








ALGORITHM ALLEY 


Binary Search 


Micha Hott 


Introduction 
by Bruce Schneier 


Binary searches are among those algorithmic staples that have 
uses everywhere. If you want to locate an entry in a sorted 
array, a binary search is the most efficient way to do so. I 
can’t think of a college course in basic algorithms that doesn’t 
cover binary searches. 

The technique isn’t perfect, however. Records must all be 
the same length and must be stored in a static array. If the en- 
tries are of variable length or in some kind of dynamic data 
structure, other less-efficient search techniques — search trees, 
interpolation searches, hashing, and the like— take over. But 
since the entry can be a key pointing to a more-complex record, 
binary-search techniques can be used in many situations. 

This month, Micha Hofri sees how efficient he can make 
a basic binary-search algorithm. Why are we bothering with 





something so basic? Micha’s analysis is interesting not so 
much in what it reveals about binary search, but in how the 
algorithm works. Good programmers do this kind of anal- 
ysis with any algorithm that has significant effects on the 
performance of the system. (At least, they do when they 
have the time and budget to program right, not when the 
deadline is in five hours and management doesn’t care what 
it looks like as long as it works.) Micha’s trade-offs — iter- 
ation versus recursion, more simple steps versus fewer com- 
plex steps— are the type that can be made almost every- 
where. Even in a world of ever-increasing processor power 
and clock speeds, a finely crafted algorithm is still a thing 
of beauty. 

By the way, I am still interested in hearing your column 
ideas, whether you want to write a column yourself or you’d 
like to see a certain topic explored. You can contact me at 
schneier@winternet.com. 


inary search is the method of choice 

for searching a list for a given key 

value. In fact, it is the optimal com- 

parison-based search algorithm 
(hashing methods can do better—with 
some trade-offs). To use binary search, 
the lists to be searched must be sorted 
(we assume in increasing order), of known 
length, and indexable in an array. This im- 
plies that the keys must be all of the same 
size, and that binary search can not be 
used to search a linked list. 

These conditions mean that the ith 
smallest key can be directly accessed, as 
A, (or Ali], using C-like notation). Binary 
search can be used to find a given key 
or to check whether or not the list con- 
tains one. The sorting implies, for exam- 
ple, that if the key value 6 (assuming all 
the keys are integers) is followed by the 
key value 10, then 7, 8, and 9 are not in 
the list. 

I'll present here a basic form of bina- 
ry search, which I refer to as “BS”; ’ll 
also discuss “BS1” and “BS2.” Much of 
the following discussion is based on 


Micha, a member of the computer science 
department at Rice University, is the au- 
thor of Analysis of Algorithms: Mathe- 
matical Methods, Computational Tools 
(Oxford University Press, 1995). He can 
be contacted at hofri@cs.rice.edu. 
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Gilles Brassard and Paul Bratley’s book 
Algorithmics: Theory and Practice (Pren- 
tice-Hall, 1988). Since BS is a “divide-and- 
conquer” algorithm, its form is naturally 
recursive; see Example 1(a). Note in line 
3 the comment L(i#+/+)/2]. (The term Lal 
is the “floor” of a, it is the largest integer 
that does not exceed a.) In particular, on 
entry, when i=0, and j=n-1, k=Ln/2]. 
To adapt binary search to check for miss- 
ing values, you simply change line 2 to 
Example 1(b). 


Analyzing Binary Search 

When implementing BS, a few design op- 
tions are possible. All considerations are 
based on computing the run time. The 
purpose here is not just to learn about BS, 
but to show the power— and limita- 
tions — of this type of analysis. 

The first question to resolve is the cost 
unit. Each basic operation in a source 
language (such as C) is taken as one unit, 
as is each comparison in BS. However, line 
3 in Example 1(a), 
for instance, needs 
three operations (al- 
though some com- 
pilers can do better 
than that). Q denotes 
the cost of a function 
call and return; there- 








in line 2, its cost is Q+1; otherwise it is 
Q+1+3+1+another call. 

To be more precise, suppose A has 1 
entries and x is equally likely to match 
each of them. If 7() denotes the total cost 
of such a call, then 711)=Q+1 and for 71, 
7(n)=Q+5+7(r), where r depends on the 
result of the comparison_in line 4 and is 
either k=Ln/2] or n— k=l n/2| (the “ceil- 
ing” of n/2 or the smallest integer 27/2). 

Although 7(7) is a random variable, we 
deal here only with its expected value, 
t(n). (For a deeper analysis, see my book 
Analysis of Algorithms: Mathematical Meth- 
ods, Computational Tools, Oxford Uni- 
versity Press, 1995.) Since x is equally like- 
ly to be each of the entries, it is with 
probability of | n/2J/2n in the lower part 
and [n/2|/nin the upper part. Figure 1(a) 
presents an equation— here, a recur- 
rence— for the mean running time. This 
kind of equation is typical for divide-and- 
conquer algorithms. The successful ap- 
proach to solving this type of equation is: 


fore, if BS terminates Example 1: BS, recursive form of binary search. 
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1. Simplify. 

2. Look for a sequence of argument val- 
ues where the equation can be solved 
by standard analytic means. 

3. Use this as a guide to guess a solution 
from a table of values produced by 
the recurrence. Then use substitution 
to prove that the guess satisfies the 
equation. 


Simplifying means replacing O+1 by a, 
O+5 by B, multiplying by n, and defining 
u(n)=nt(n). This leaves us with the equa- 
tion in Figure 1(b). We then choose val- 
ues of 1 for which the troublesome floor 
and ceiling functions relent: powers of 2, 
or n=2”™. The result is in Figure 1(c). 

The relation n/2=2”-! suggests a 
change of notation, so we define v(m)= 
u(2™) as in Figure 1(d). This is finally a 
standard, first-order recurrence, which can 
be solved by the simple iteration in Fig- 
ure 1(e). 

So much for these special arguments; 
writing m=/g n (binary logarithm), we have 





iy 


es 


xample 2: BS1, first iterative form of BS. 





Table 1: Average time per search (in us) 
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un=n(Blg n+a). Clearly, n(B lg n+) 


cannot be right for all values of 1, since 
the recurrence generates integer coeffi- 
cients and /g 7 is not integral unless n is 
a power of 2. We must return to the orig- 
inal recurrence for u(”), in Figure 1(b), 
and use it— floors, ceilings, and all—to 
generate several values, compare them 
with the special solution, and look for a 
pattern. Here, after computing about ten 
values, everything falls into place; when 
n=2™+r, O<Sr<2™ where m=Lig n\ then 
the solution in Figure 1(f) fits all the gen- 
erated values. When 7=0, we get back to 
the special solution. Testing by substitu- 
tion into Figure 1(b) is successful, so 
t(m=u(n)/n=a+tB (Lig nj+2r/n). Since 
r/n < 1, this result supports the standard 
claim that “BS runs in logarithmic time.” 

So much for the expected run time. De- 
termining its variability requires a differ- 
ent kind of computation, one that ad- 
dresses the probabilistic structure directly. 
I show this in my book; a partial result is 
that the number of iterations has only two 
possible values, Lig m] and | Ig n| Gf n=2™, 
these are both m). 


Recursion Elimination 

Having computed the expected cost of BS, 
let's try to reduce it. One obvious source 
of cost is the recursive call at each level 
of the procedure. This is “tail recursion,” 
where the last instruction performed at 
each level is a single recursive call. The 


call is easy to replace using a single loop; 
see Example 2. The logic is identical to 
that of BS, except that a new call is not 
initiated at each level. Instead, either the 
left or right end of the interval is adjusted. 

The logical structure of such a program 
parallels that of a recursive program, but 
the analysis is entirely different. In BS, ev- 
ery instruction was done (at most) once 
at each level; not so in BS1. That’s why 
the left-most column is added in Exam- 
ple 2: The number of times each line is 
repeated is given as a function of the 
searched interval size. The symbol a(7) 
denotes the number of times that the main 
instructions (lines 4 and 5) are executed. 
We define p, as the probability that the 
condition in line 5 is satisfied and g,=1-p,. 
We make the crucial assumption that p, 
depends in the same way on the interval 
size each time line 5 is reached. This is 
the precise analog of the assumption we 
made when analyzing BS— and for the 
same reason. Regardless of which subin- 
terval still needs to be searched, the as- 
sumption that x is equally likely to be in 
any position translates without change: 
The previous comparisons delimit the 
subinterval to be searched, but provide 
no other information on the location of x. 
Hence p, always has the same functional 
form as at the first iteration, L7/2)/n, and 
q =| n/ 2V N1. 

If a’ is the cost of the lines performed 
once—l1, 2, 3, and 8—then a’=Q+2. B’ 
counts the cost that recurs a(n) times— 
lines 3, 4, 5, 6, or 7— so B’=6. The equa- 
tion to determine a(n) follows from a de- 
scription of the search: Starting with an 
interval of size n, one iteration leaves us 
with an interval of the size Ln/2J Gn prob- 
ability Ln/2\/n) or [ n/2| Gwith the com- 
plementary probability | n/2 Vn); hence 
the equation in Figure 2(a). Up to a fac- 
tor of B, this is the same as Figure 1(a), 
so the solution is familiar: n=2//8 nJ+r 
yields the result in Figure 2(b). The 
amount saved by this modification is 
t(m)—-t,(7, and writing it in full yields the 
equation in Figure 2(c). 

The last relation allows us to estimate 
QO (without reading arcane compiled 
code). Table 1 represents the average time 
per search (in us) on a standard work- 
station running under a UNIX-like oper- 
ating system. Consider for the moment 
only the left four columns; compute for 
each n the value Lig n}+2r/n and perform 
a linear regression between these values 
and the column labeled BS-BS1. This 
yields the intercept —0.248 and slope 0.383. 
Since the intercept (in admittedly flexible 
units) is given in Figure 2(c) as —1, the 
value of QO in these units is =2.54— about 
two and a half basic operations. 

The cost of recursion is not trivial for a 
procedure with such a short body. Still, it 
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Figure 3: Three-way comparison. 


(continued from page 130) 
is hardly onerous. However, this evalua- 
tion disregards two important facts: 


¢ QO depends on the number of variables 
pushed into (or popped from) the stack; 
here 3(ij,x). This is actually two ad- 
dresses and x. It would differ for calls 
with other argument vectors. 

e O’s value is materially influenced by de- 
tails in the implementation of stack op- 
erations and cache and system-storage 
management. On an older, slower mini- 
computer with essentially the same op- 
erating system, Q=1.9. This approach 
to estimating Q failed on a different 
UNIX-like system, when BS suffered 
penalties for recursions of depth beyond 
5 that raised the running time by an un- 
expected factor of 5 to 8! (Yet another 
experiment suggested that O without 
stack-management overhead is some- 
what less than 2.) This was the highest 
price I saw paid for a flexible, dynam- 
ic memory-management policy. 


Three-Way Comparison 
The next modification was prompted by 
the observation that T(7) is essentially 






Example 3: BS2, second iterative form 
of BS. 





constant, while BS 
and BS1 sometimes 
“locate” the desired 
key early in the 
search (BS and BS1 
are unaware of this, 
since equality is nev- 
er tested, only in- 
equality). The value 
x could be in posi- 
tion Ln/2] (located at 
the first stab) but the 
routines would just go chugging along, 
only to return there /g n steps later. Ex- 
ample 3 adds just such a test. While BS1 
always makes two comparisons per iter- 
ation, BS2 needs two in about half of its 
iterations, and three in the other half — 
but presumably fewer iterations. Is this a 
good idea? Analysis should provide the 
answer: We find in BS2 the same proba- 
bility p, used before, Pr(x<Alk}) =.n/2\/n, 
In addition, we have p,, defined as the 
probability that x=A[R], given that x is not 
in the first k positions; hence p,=1/(n—R). 
The dependence of the exact number of 
operations on the results of the compar- 
isons is somewhat more complex here. It 
is evaluated by considering the average 
number of iterations BS2 will perform, 
again assuming that x is in the array and 
is equally likely to be any element. Read- 
ing the evolution of s() from the code 
in Example 3 yields the equation in Fig- 
ure 3(a). This equation is more complex 
then those presented so far; for example, 
two initial values are required to drive the 
recursion. They too can be deduced by 
reading BS2: s(1) is obviously 0, and s(2) 
is always 1. Since k=Ln/2], then n—R-1= 
[ 2/2 |-1. 

Define the function b(7)=ns(n), to get 
the equation in Figure 3(b), where the 
initial values are b(1)=0 and b(2)=2. Pick- 
ing m as a power of 2 does not help as 
before; instead, we pick n=2”—1, then 





Figure 4: Form of the guessed solution. 


Figure 5: Determining what BS2 saves over BS1. 
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[ n/2|-1=Ln/2J=2”-1-1. We find a first- 
order recursion, similar to the equation 
in Figure 1(c). This is shown in Figure 
3(c). Using the initial value for m=1, 
which is b(2-1)=1-s(1)=0, a simple un- 
reeling reveals the solution in Figure 3(d). 
Trying to guess the general solution is 
more difficult (I needed more than 30 
terms to see the pattern) because the in- 
crements change as reaches 3/2 n* 
(where n* represents 2/8 J). Figure 4(a) 
shows the guessed solution; Y(7) is giv- 
en in Figure 4(b). Substitution confirms 
this as a solution to the equation in Fig- 
ure 3(b). 

Finally we compare the costs ¢,(7) and 
t,(m). First, how many iterations, on av- 
erage, does BS2 save over BS1? The dif- 
ference is a(n)—s(n), and is given in Fig- 
ure 5(a) for the range n*<n<3/2n"*. 

As n increases from n* to 3/2n*, this 
difference varies from 1.5 to 0.66 (ap- 
proximately). In the rest of the range, the 
equation in Figure 5(b) varies corre- 
spondingly, approximately from 1.33 to 
1.5. The savings are modest and are es- 
sentially independent of the size of 7, but 
dependent on the ratio n/n*. Hence the 
difference between the running times can 
be roughly set to Figure 5(c). 

Allow the same cost C for any opera- 
tion (comparison, arithmetic, or assign- 
ment) so that the two cost factors in Fig- 
ure 5(c) are nearly 6C and C (for two 
operations, at about half the iterations), 
respectively. Using only /g n*, the lead- 
ing term from the solution for s(7), shows 
that BS1 is better when the equation in 
Figure 5(d) applies. 

If we take 4/3 as a representative val- 
ue for A,,, we can expect the extra check 
in BS2 to pay off unless the array is more 
than about 200 entries long, with a rela- 
tively important dependence on the ratio 
n/n*. Table 1 bears this out. Since the 
logarithm of m* appears in this relation, 
the critical length is sensitive to minor 
variations in the implementation. Higher 
precision requires consideration of the 
compiler and the machine code it gen- 
erates, as well as details of the machine 
architecture, such as availability of in- 
crement/decrement instructions, separate 
data and instruction caches, and the like. 

Note that in some machines, condition 
codes (with computed branches) allow for 
a three-way comparison at no added cost. 
If a compiler is designed to take advan- 
tage of this and can use a single compar- 
ison for lines 5 and 7 of BS2, then it will 
outperform BS1 on the average for any 
value of v. Another possibility is to code 
it directly in assembly language. Since bi- 
nary search is used so frequently, this may 
be a reasonable approach. 


DDJ 
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PROGRAMMER’S BOOKSHELF 


Algorithms for C and 
(++ Programmers 


Dean Gahlon 


find computer books that deal with al- 

gorithms more interesting than, say, 

entry-level C or C++ books. Algorithm 

books provide tools I can use directly 
to build programs, and generally are last- 
ing reference works. Practical Algorithms 
for Programmers, by Andrew Binstock and 
John Rex, and Practical Algorithms in C++, 
by Bryan Flamig, both fit this description. 

Although these two books cover much 
of the same ground, they approach the 
topic from different angles. The focus of 
Binstock/Rex is on the algorithms (ex- 
pressed in C), while that of Flamig is more 
on expressing algorithms in C++. In oth- 
er words, Binstock/Rex is an algorithm 
book; Flamig is a C++ book covering al- 
gorithms. 

In general, Binstock/Rex is more ac- 
cessible than Flamig, both in writing and 
coding. The authors go into detail about 
the trade-offs among the variants of var- 
ious algorithms. They do a good job of 
giving the information you need to make 
an informed decision as to the best ver- 
sion for a particular application. Flamig, 
on the other hand, is briefer and tends to 
say less about the possible options. As to 
the coding, Binstock/Rex is clearer, with 
comments explaining each section of the 
program. Comparatively, the code in 
Flamig is somewhat terse. (I’ll admit that 
part of my preference for Binstock/Rex is 
that I like their indentation style more than 
Flamig’s. Also, Binstock and Rex use more 
white space, which makes the code more 
readable.) 


Reading for Reference 

For the most part, Practical Algorithms for 
C Programmers is better organized than 
the Flamig book. For example, Binstock/ 
Rex thoroughly cover string searching in 
one chapter (including some interesting 
approximate-string algorithms), then move 
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on to cover other topics. Flamig, howev- 
er, discusses string searching in part of 
one chapter, then returns to the topic again 
in a later chapter on finite-state machines. 
Although it makes some sense to put that 
particular algorithm (the Aho-Corasick 
string-matching algorithm) in the chapter 
on FSMs, a potential reader is likelier to 
say “I want an algorithm for string search- 
ing” than “I want an algorithm using finite- 
state machines.” For reasons such as this, 
Binstock/Rex is the better of the two as a 
reference work. 

Although it’s probably a small thing, I 
also found the index in Binstock/Rex to 
be more helpful and complete than the 
index in Flamig. I tested this by looking 
up “string searching” in the index to each 
book; there was an entry for it in Bin- 
stock/Rex, but none in Flamig. 

I also prefer the references in the Bin- 
stock/Rex book. They use notes at the 
end of each chapter, with informative, ex- 
planatory sentences. Flamig has just a bib- 
liography at the end of the book. While 
the latter is more scholarly, I find going 
to the back of the book to find further ref- 
erences breaks up the flow of text. I pre- 
fer all the information on one topic to be 
together. I also like Binstock/Rex’s refer- 
ences because they mention the draw- 





backs of the article they’re referring to. 
For instance, in listing the ElfHash rou- 
tine, they warn you that some published 
versions of the routine leave out a crucial 
character. The erroneous version would 
cause the function to return zero every 
time it was called, which isn’t exactly de- 
sirable. 


Beyond C and C++ 

If what you’re looking for is a C++ book 
that goes beyond teaching the language, 
Flamig is fine. Hidden within its code list- 
ings are some interesting practical uses of 
some of the subtleties of C++. One ex- 
ample is combining the placement new 
operator with a class’s copy constructor 
to construct an instance of that class in 
place. 

One interesting idea in Flamig (which 
forms the basis of a good portion of the 
book) is that of generators. A generator is 
something like an iterator (as widely repre- 
sented in C++ literature and class libraries). 
However, rather than stepping through an 
existing set of objects, as an iterator does, 
each call to the generator generates the 
next object in the set. I think the idea of 
generators could lead in several poten- 
tially useful directions. However, the au- 
thor’s introduction of them results in a 
lengthy discussion of unwinding recursion 
into iteration. This ends with some semi- 
readable code involving GOTO statements. 
(I’m afraid I’m not as well-disposed to- 
ward GOTOs as Flamig is.) Although I 
find the idea of generators intriguing, I’m 
not quite sure that it’s worth the cost of 
the readability of the resulting code. 

In some sense, the main advantage to 
Flamig isn’t so much the algorithms as the 
practical examples of class construction 
and other routines using C++. It is not, 
however, a guidebook for object-oriented 
design. Except for the idea of generators, 
the entire question of object orientation is 
relatively incidental to the book’s presen- 
tation. But since there are many other 
books on object-oriented design out there, 
I don’t consider this a flaw in the book. 
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Se Fingerspitzengefuhl. Literally, “finger-tip 
sea feeling.” As a German idiom, the word is 


saisuiad : used to indicate sensitivity. As in,“that 
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xa Sensitivity. At Harvard Translations, we’re 
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translating a technical manual or need a 
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Got a 
Life? 


Ready to bail? Then the Rogue Valley—Oregon’s Sunbelt—is the place 
for you and your business. Just check out our web page. Awesome 
recreation. Six internet pipes and ISDN. Music and Theatre. 
Multimedia Institute. Rafting. International airport/I-5 access. 
Software support system. Snowboarding. College town close-by. 
We're wired and ready for YOUR business. The Rogue Valley-what a life! 


SOUTHERN 
OREGON 


Wired And Ready For Software 


Southern Oregon Regional Economic Development, Inc. 
Medford * Grants Pass ¢ Ashland 
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Beyond the Ordinary 
Quite often, Flamig’s Practical Algorithms 
in C++ deals with some slightly more ad- 
vanced topics — permutations, graphs, fi- 
nite-state machines, and the like. Bin- 
stock/Rex’s Practical Algorithms for C 
Programmers, however, takes on some 
out-of-the-ordinary topics: date and time 
calculations, arbitrary- precision arithmetic, 
and data validation and integrity. The ma- 
terial on heaps is much more complete in 
Flamig than it is in Binstock/Rex. Bin- 
stock/Rex, though, covers more basic data 
structures: linked lists, trees, and the like. 
To be fair, Flamig apparently covered 
much of this in his companion book Prac- 
tical Data Structures in C++ (John Wiley 
& Sons, 1993, ISBN 0-471-55863-X). 
Hashing is a good example of the two 
books’ relative coverage of a specific top- 
ic. (Hashing is a method of storing data 
so that it is retrievable via what is es- 
sentially a table lookup. A hash function 
converts the key for the item being stored 
into an index into the hash table.) Both 
books cover the topic adequately — in 
fact, both present the same optimal hash 
function, taken from the same source. 
However, Binstock/Rex goes into greater 
detail in explaining the trade-offs in- 
volved in the various types of hashing 
(or, more accurately, collision handling). 
Practical Algorithms for C Programmers 
also details some ideas on how to get 
good performance out of hashing. Flamig 
covers hashing more broadly, discussing, 
among other things, a class that imple- 
ments file-based hashing (included on 
disk) and rebuilding the hash table when 
it grows too large. 


Conclusion 

Both Practical Algorithms for C Program- 
mers and Practical Algorithms in C++ pre- 
sent a wide range of algorithms in source- 
code form and go into detail when 
describing specific algorithms. Neither 
book leaves algorithms as exercises for 
the reader, as do many algorithm books 
that are designed as textbooks. 

I prefer Binstock/Rex’s Practical Algo- 
rithms for C Programmers because it cov- 
ers more ground. However, it’s a close 
race. Flamig’s focus on C++ issues is a 
strong pull. Although Flamig’s book is 
more theoretical than that of Binstock/Rex, 
it still keeps close to the “practical” in its 
title. (The practicality of the algorithms in 
Binstock/Rex speaks for itself.) Bin- 
stock/Rex has a minor disadvantage in 
that getting the source code on disk re- 
quires a separate payment to the publisher, 
because it’s not included with the book. 
To me, however, that’s a small problem. 


DDJ 
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Walnut Creek CD-ROM has announced 
The Official POV-Ray CD-ROM, an offi- 
cially sanctioned compilation of re- 
sources for the freeware POV-Ray ray- 
tracer by a POV-Team member. It is both 
PC and Mac compatible, with prefor- 
matted Mac-folder layouts. More than a 
simple collection of files, the Official 
POV-Ray CD is an indexed, cross- 
referenced guide to POV-Ray and 3-D 
computer graphics. The global index has 
over 10,500 lines of descriptive text for 
the 3113 files on the CD-ROM. 

Included on the CD is Version 2.2 of 
POV-Ray, with precompiled binaries for 
MS-DOS, Macintosh, Amiga, and Linux. It 
also contains unofficial compiles for AXP 
(NT/OSF), BSDI, FreeBSD, HPUX, Inmos 
T800, NeXT (68k,i386,hppa), NT (386), 
OS/2, Power Macintosh, MIPS R4000 (NT), 
RS/6000, SGI-IRIX, and Sun. The full 
source code for POV-Ray 2.2 is provided 
for those wanting to compile their own 
binary. The CD sells for $39.95. 

Walnut Creek CD-ROM 

1547 Palos Verdes Mall, Suite 260 
Walnut Creek, CA 94596 
510-674-0783 
http://www.cdrom.com 


Microsoft has announced two new SDKs 
for Internet-related development. The on- 
line Internet SDK is for content providers 
and Webmasters who create both Web 
content and Web sites, while the Internet 
Business Development Kit is targeted for 
resellers and system integrators. 

The Internet SDK will provide— in an 
online format— information and tools tra- 
ditionally delivered by disk-based SDKs. 
You will get access to authoring tools, such 
as “Blackbird,” server software, including 
“Gibraltar,” browser software such as the 
Internet Explorer; technologies such as In- 
ternet Server API CISAPI) and OLE; and li- 
braries with current Internet product betas. 

The Internet Business Development Kit 
will include a beta version of the Microsoft 
Windows NT Internet server (code-named 
“Gibraltar”) the Internet Assistant for Word, 
Word Viewer, which allows people who 
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don’t use Word to view, print, and follow 
hyperlinks in Word documents posted on 
the Internet, the Internet Explorer 2.0, an 
Internet browser designed for Windows 
95, and a beta version of “Blackbird,” 
which includes components for design, 
authoring, and distribution of multimedia 
applications. Also included in the kit will 
be reviewers guides, white papers, demo 
scripts, and presentations. 

Microsoft Corp. 

1 Microsoft Way 

Redmond, WA 98052 

206-882-8080 

http://www.microsoft.com 
ibizkit@microsoft.com 


Great Circle, from Geodesic Systems, is an 
automatic memory-management system for 
C/C++ programmers. The tool is designed 
to automatically eliminate bugs in C/C++ 
programs. Unlike manual memory man- 
agement, which relies heavily on debug- 
ging, Great Circle automatically fixes mem- 
ory bugs without programmer intervention. 
The tool supports all C/C++ constructs, in- 
cluding unions, multiple inheritance, poly- 
morphism, interior pointers, arrays, com- 
position, and exceptions. The tool, which 
supports most popular operating systems 
and C/C++ compilers, sells Gin object-code 
format) for $300.00-$500.00 for PCs and 
for $700.00— $1200.00 for workstations. 
C++ source code is also available. 
Geodesic Systems 

4745 N. Ravenswood Avenue, Suite 111 
Chicago, IL 60640 

312-728-7196 

info@geodesic.com 


ParaSoft has announced Insure++ 3.0 (for- 
merly Insight), an automatic, run-time 
error-detection environment. Insure++ lets 
you quickly pinpoint bugs and provides in- 
formation necessary them. In particular, the 
tool detects the “most wanted” errors: mem- 
ory corruption; operations on uninitialized, 
NULL or “wild” pointers; memory leaks; er- 
rors that allocate and free dynamic memo- 
ry; Operations on unrelated pointers; and 
more. Version 3.0 enhancements include 
support for Sequent, Tandem, VMS, Lynx, 
and Linux platforms, in addition to the pre- 
viously supported Sun, HP, IBM, DEC, SGI, 
and x86. Version 3.0 supports threads and 
precompiled headers, and also detects leaks 
by simply linking (dynamic or static). In- 
suret++ 3.0 is priced from $1995.00 for a sin- 
gle-machine license. 

ParaSoft Corp. 

2031 S. Myrtle Avenue 

Monrovia, CA 91016 

818-305-0041 

http://www.parasoft.com 


Atemi has announced the release of its 
NetShade 2.0 network encryption software. 


NetShade 2.0 can be used in conjunction 
with Web browsers, e-mail systems, and 
other applications to secure information 
sent over the Internet. NetShade v2.0 is 
designed to work across different plat- 
forms: For example, a Windows user will 
be able to communicate securely with a 
Macintosh user. 

NetShade combines the RSA public-key 
cryptosystem with a collection of encryp- 
tion ciphers, including DES and Triple 
DES. Users determine which algorithm will 
be used to encrypt a session, depending 
on how much security is appropriate. Oth- 
er NetShade 2.0 features include PGP- 
compliant authentication and on-the-fly 
connection management. The initial re- 
lease of NetShade 2.0 will support Win- 
dows 3.1 and the Macintosh. Subsequent 
releases will support Windows 95, Win- 
dows NT, UNIX, and other platforms. 
Atemi Corp. 

202 West Hill Street, Suite 3 West 
Champaign, IL 61820 
217-352-3688 
http://www.atemi.com 


America Online has announced its AOL 
Developers Studio, a program that opens 
the AOL online platform to third-party de- 
velopers, enabling them to integrate their 
software with AOL. The program consists 
of software tools for adding online func- 
tionality, technical support, and product 
management to assist partner development, 
and marketing initiatives to showcase part- 
ner products to the rapidly expanding AOL 
audience. 

The AOL Developers Studio SDK pro- 
vides the following for both Windows and 
Macintosh: one-button access, allowing 
limitless links for members to instantly 
launch to sites on AOL or the Internet, and 
also lets developers create added value to 
an existing software product; custom ac- 
cess, that lets developers control the UI 
while enabling members to download files 
and send/receive e-mail, leveraging AOL’s 
up-to-date content, including news, stock 
quotes, and mail; interapplication com- 
munications, so that you can write add-on 
applications for the AOL service enabling 
users to access the power and interactivi- 
ty of AOL, including e-mail, chat, instant 
messaging, file transfer, and other func- 
tions; and a games API, for developing in- 
teractive, multiplayer online games for play- 
ers in and out of the AOL community. 
America Online 
8619 Westwood Center Drive 
Vienna, VA 15469 
703-918-2681 
SDKPartner@aol.com 


Starfish Software, the new company head- 
ed by Philippe Kahn, has released its 
Dashboard SDK, an API with C/C++ 
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and Delphi 32 source code. The Dash- 
board SDK will let you create Dashboard 
Loadable Modules (DLMs) that can be ex- 
ecuted from Dashboard 95, a Windows 95 
application that gives users better organi- 
zation of their work area, instant access 
to frequently used applications, and a com- 
mon interface across Windows 3.x, Win- 
dows NT, and Windows 95. One benefit 
of DLMs is that they provide single-click 
access to a custom or vertical-market ap- 
plication. 

Starfish Software 

1700 Green Hills Road 

Scotts Valley, CA 95066 

800-765-7839 
http://www.starfishsoftware.com 


IST’s OpenExchange DLL 1.0, a program- 
ming library for importing and exporting 
data, lets you read and write spreadsheet 
files in all major formats without the over- 
head of OLE or DDE. You can use the DLL, 
for instance, to read data into memory vari- 
ables, then use that data to update your 
database with your own existing drivers. 
Likewise, you can output data to a new 
file from memory, or transfer data direct- 
ly from one file into another. The DLL is 
compatible with Visual Basic, C++, Del- 
phi, PowerBuilder, Visual FoxPro, Clarion, 
and other development environments, and 
supports all major spreadsheet files (Ex- 
cel, Lotus, Quattro Pro, dBase, and oth- 
ers). The DLL sells for $295.00. 

IST 

P.O. Box 3774 

Joplin, MO 64803 

417-781-3282 
74777.2651@compuserve.com 


Ventana Communications has announced 
a pair of book/CD-ROMs for Windows 
developers, one covering Delphi and the 
other Visual Basic. Written by Harold 
Davis, the Delphi for Windows Power Tool- 
kit covers dynamic-memory allocation and 
management, creating DLLs, applying VBX 
controls, using DDE and OLE, and the 
like. The Visual Basic 4.0 Power Toolkit, 
authored by Richard Mansfield and Evan- 
gelos Petroutsos, focuses on working with 
databases (SQL, data control, and the like), 
OLE Automation, workgroup networking 
(MAPI, POPMAIL, TelNotes), and various 
API issues (bitmapped graphics, manag- 
ing .INI files, and more). The CD-ROMs 
include companion code, custom con- 
trols, shareware, sample files, and utili- 
ties. The book/CD-ROM packages sell for 
$49.95 each. 

Ventana Communications 

P.O. Box 13964 

Research Triangle Park 

NC 27709-7955 

800-743-5369 
http://www.vmedia.com/index.html 
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Microhelp has announced its OLETools, a 
collection of OLE controls for program- 
mers using development environments 
such as Visual Basic, Visual C++, and sim- 
ilar tools. The OLETools package includes 
more than 100 16- and 32-bit OLE con- 
trols. Among the categories of controls are 
those for: interface, data and time, multi- 
media, and miscellaneous (networks, sub- 
classing, gauges, dials, and the like). OLE- 
Tools sells for $189.00. 

The company has also announced 
Code Complete, a suite of tools includ- 
ing Splash Wizard (to add splash screens 
and built-in version checking), Code An- 
alyst (for code dissecting and cross ref- 
erencing), and AutoCoder (for standard- 
izing module and function headers in 
team-development environments). Code 
Complete sells for $249.00. 

Microhelp Inc. 

4211 J.V.L. Industrial Park Drive NE 
Marietta, GA 30066 

770-516-0889 
76325.3207@compuserve.com 


Gryphon Microproducts has released 
W3MAGIC for World Wide Web develop- 
ment. W3MAGIC is a programming lan- 
guage that adds over 100 new high-level 
tags and functions to HTML, from anima- 
tion and dynamic buttons to counters and 
user logs. It allows you to protect your 
data and code by encrypting it. Encrypt- 
ed code can be executed just like normal 
HTML, but appears unintelligible when 
copied. The language works with all 
browsers. 

In addition to providing special effects 
such as animation, wipes, fades, and push- 
es, W3MAGIC lets you gather statistical 
information about visitors to your page, 
including counters and user identification 
by country, originating link, browser type, 
and pages accessed. It can display ran- 
dom text, random GIFs, and dynamically 
generated graphs, and can perform table 
lookups. 

W3MAGIC, which sells for $399.00, is 
available for Solaris, Sun, PC Linux, BSDI 
UNIX, AIX, BSDI, FreeBSD, and Novell 
UNIX. An account with cgi-bin access is 
required to use this tool. 

Gryphon Microproducts 

12808 Ruxton Road 

Silver Spring, MD 20904 
301-384-6868 
http://www.fox.net/~w3magic/ 


SuccessWare has announced an SDK for 
its SuccessWare Database Engine 2.0 
(SDE2) (formerly known as ROCK-E-T), a 
replaceable database engine for Visual Ba- 
sic 4.0, Visual C++, and any DLL/OCX de- 
velopment environment. The SuccessWare 
Database Engine technology allows for a 
common xbase-style (record-based) data 





navigation and syntax during program de- 
velopment with minimal concern for the 
ultimate format of the database. This leads 
to movement between database environ- 
ments with little or no code modification. 
Also supported is database-compatible 
concurrent-access locking on networks. 

SDE2 supports table, index, and memo 
files for CA-Clipper (NTX), FoxPro 2.x 
(IDX/CDX), and HiPer-SIx (NSX) systems. 
It also supports freeform-text searching; 
fixed-length fields that automatically ex- 
pand to meet the input requirements; im- 
age/BLOBs storage and retrieval without 
any intermediate files; conditional index- 
es; instant index filters for absolute con- 
trol over the database views; and record- 
level data encryption. 

The SuccessWare Database Engine 2.0 
SDK is priced at $299.00 per developer li- 
cense for multiuser-application creation. 
It is royalty-free. 

SuccessWare International 
27349 Jefferson Street, Suite 110 
Temecula, CA 92590 
909-699-9657 
74774.2240@compuserve.com 


NobleNet has announced its OneDriver 
ODBC SDK, which allows you to cus- 
tomize external functions on either the 
client side or server side (or both) of a 
client/server database application. This 
permits deployment of applications in two- 
sided (thin or fat client) and two-model 
(two or three tier) architectures, including 
Oracle, Sybase SQL Server, Informix, and 
others. 

The SDK conforms to Microsoft ODBC 
2.0 and is backward compatible with 1.0. 
The OneDriver ODBC SDK provides a 
universal, client-based ODBC-2.0 driver 
that automatically receives and interprets 
database calls and responses and an SQL- 
based source-code module that lets you 
customize access to external functions. 
Depending on the application function- 
ality desired, processing is directly or in- 
directly remote to a server-based ODBC 
driver library. The library is used to ac- 
cess the selected database or databases 
via C source code that mirrors the SQL 
code on the client. The OneDriver ODBC 
client-side driver is WinSock compliant, 
runs on both TCP and IPX, and has been 
certified on over 20 WinSock-compliant 
products. 

NobleNet Inc. 

337 Turnpike Road 
Southboro, MA 01772 
508-460-8222 
sales@noblenet.com 
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SWAINE’S FLAMES 


Veronica, Billionaires, and Spelling 

eronica, 7. A technique in which the matador stands immobile while passing the cape 
V slowly before the charging bull. 

Veronica, 7. A technique in which the system stands immobile while passing menu items 
slowly before the dozing user. 

The similarity sorta makes you wonder if the traditional Spanish protocol for interacting with 
bulls influenced the traditional Minnesota protocol for interacting with Gophers. 

Speaking of rodents, apparently Steve Jobs is now a billionaire. (Oh, maybe that was a little 
obscure. Here’s what I was thinking: Steve’s company Pixar is working closely with Disney on 
some all-digital-animation feature films, and Disney is closely associated with a mouse. Hence the 
rodent reference, you see.) 

Anyway, with the completion of Pixar’s first film, Toy Story, the paper value of Steve’s holdings 
adds up to more than he ever had while at Apple. There are enough ironies here to satisfy even a 
journalist’s appetite, not the least of them being that it was Pixar, acquired from George Lucas in 
1986, rather than NeXT, the company Steve built from scratch after leaving Apple, that ultimately 
paid off. If Steve is a role model, the message for Jobs wannabes is apparently, “Hitch your 
wagon to someone else’s cast-off dream.” 

“I don’t think I’m personally a role model,” Bill Gates told Newsweek interviewers in a special 
“Kissing Up to the Billionaire” issue of Newsweek that contained an excerpt from Bill’s book, The 
Road Ahead. Pass the word. America’s youth needs to know this. 

I hope you appreciate the sacrifices I make for you. For example, I read everything written 
about Billionaire Bill so that you don’t have to. What you get here is just the cream. You won't 
read, for example, “The King of Comdex, if not the computer industry, if not the future itself. The 
richest man on the planet, and maybe the smartest: William Henry Gates III.” You’d read that in 
the KUTTB issue of Newsweek, under Steven Levy’s byline. 

<Murphy Brown voice> 

“Jeez, Steven, did you really write that tripe, or just hold your nose while an editor lathered it on?” 

</Murphy Brown voice> | 

Everybody is writing about Bill. Here, though, is the bottom line. Ready? 

It’s not about Microsoft and how it’s missing the Internet window or not missing the window, 
or how Netscape is going to be what Microsoft might have become, or Microsoft is really going to 
become what Netscape is expected to become, or about Bill’s vision of the future, which is a 
mosaic (you should pardon the expression) of other people’s dreams, whether cast-off or not. 

It’s not about his divinity, another topic explored in Newsweek, or his house, or his attitude 
toward Apple or IBM or the Justice Department. 

It's about his attention span. 

Many of the pioneers of the information revolution were in it for the thrill of the new, and 
when it started to get familiar, they lost interest. Some left and did something else, like Mitch 
Kapor, who became a lobbyist. Some stayed and went through the motions, like, well, you know 
a few, I'll bet. And some were one-trick ponies who had nothing to offer after the first trick. 

Here’s the bottom line: Bill won’t leave. He won't lose interest, he won't get bored, and he is 
not a one-trick pony. He is, though, a one-track mind, and that track is software. As long as 
there’s software, expect him to be involved with its making and distributing. 

Now isn’t that a thought to wake you in the middle of the night in a cold sweat? 

Snit of the month. The growing use of e-mail, not to mention Web-page publishing, threatens to 
reverse the trend toward illiteracy among the supposedly educated without at the same time 
improving their spelling. The following flame is intended only for those who need it: The word 
“independent” contains no “a”s. Zero. None. Nary an “a”. It is not spelled “independant.” Don’t make 
me tell you again. The word “separate,” on the other hand, has two “a’s. It is not spelled “seperate.” 
There is no common English word that begins “sepe-”. Flush that sequence from your cache. 

I wouldn’t have to spend time on this stuff if you would all just shape up. 


WechaD Scud 


Michael Swaine 
editor-at-large 
mswaine@cruzio.com 
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Introducing 


CodesSQL 


“All the Speed, All the Power, 
None of the Royalties” 


fe =YouGeta High Performance ODBC SQL Engine! 


|  CodeSQL uses the ODBC standard to provide you with 
Oracle-level SQL capabilities. Deploy a wide variety of 
applications using the provided single-user, multi-user, and 
client/server configurations. 


Use CodeSQL from C, C++, Visual Basic, Delphi, FoxPro, 
PowerBuilder, or any other front-end with ODBC support. 





True Industrial Strength 


CodeSQL conforms to the ANSI SQL Level 2, Oracle and 
ODBC Extended SQL grammar standards. For example, you 
can create/drop tables, views, indexes, and constraints. Inner 
and outer joins, nested queries, and other advanced SQL 
operations are all supported. You can even set isolation levels. 


xBASE Compatible 


CodeSQL uses xBASE files as its native file format. Built 
using CodeBase technology, CodeSQL is multi-user compatible 
with the data, index, and memo files of dBASE and FoxPro. 


Nothing Moves Data Faster 


CodeSQL is throughly optimized for performance. With our 
extensive query optimization, the more complex the query the 
more the relative performance increase. Gain even more speed 
through our automatic buffering which reduces network load, 
and with our statement caching which gives you static SQL 
performance with dynamic execution. 


CodeSQL provides these additional benefits: 


¢ Security 

¢ Transaction Processing 
¢ Full SQL Syntax Documentation 
¢ Logging and Audit Trails 
¢ 32-Bit Windows Support 
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—PC Magazine, April 1995 


Target 16- and 32-bit applications 
from one environment 


Your no-risk migration path to Windows 95 is here. Borland® C++ 4.5 
runs under Windows 95 today and includes Windows 95 header files and 
import libraries so you can create native Windows applications. Only 
Borland C++ 4.5 lets you create powerful ANSI C and C++ applications 
for DOS, 16-bit Windows, and 32-bit Windows applications from a single 
IDE. Plus, OWL helps you deliver true single source 16-and 32-bit 
Windows applications. That means less work, less frustration, and more 
free disk space on your way to Windows 95. 


C++ Sets the Standard 


The Plum Hall Validation Suite for C++ 


BorlandC++4.5 Microsoft Microsoft 
Visual C++ 1.51 Visual C++ 2.0 
General coverage of C++ features 10 8 9 
Templates 5 0 6 
Exceptions 10 0 9 
Runtime Type Information (RTTI) 9 0 0 
Namespaces | | 0 0 0 
Stringency of diagnostic messages | 9 9 9 
Tracking minor changes in draft standard 6 1 1 
Support for block-local class functions 9 0 0 
Revisions of obsolete cfront cases 10 7 7 
Weighted average 8.0 2.6 5.3 


Larger scores represent better performance. 10 represents 100 percent compliance. 





—PC Magazine, April 11, 1995 


Follow the leader 


Borland C++ is the C and C++ speed leader, beating all other competitors 
in PC Magazine’s benchmark tests for compile and link speeds. And 
Borland is the language standards leader, with consistent support across 
16- and 32-bit targets for the latest C++ language implementation. 


The productivity edge 


Full support for VBX controls in both 16- and 32-bit applications, includ- 
ing Windows 95! A multi-target project manager to handle complex 
dependencies, as well as multiple executables, DLLs, and libraries, in a 
single build. And complete OLE support, as well. It’s all here. Everything 
you need to create native Windows 95 applications right now. 


CodeGuard locates bugs automatically 


Increase productivity by an order of magnitude! CodeGuard™ for Borland 
C++ 4.5 saves you time and frustration. It automatically pinpoints hard- 
to-find memory and runtime library resource bugs in your 16-bit 
Windows applications. CodeGuard works with the Borland C++ 
integrated and standalone debuggers to automatically validate Windows 
API and C runtime library parameters and return values for functions 
most vulnerable to memory corruption. You can easily rid your applica- 
tions of bugs that could take days or even weeks to find. 
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ie for Bortand’ C++ 4.5 


The world-standard C and C++ ‘S Locates memory bugs automatically! 


Buy Borland C++ 4.5 today 
and get the Programmer’s 
Resource CD FREE! 


Includes more than 400Mb of programming 
utilities, C and C++ source code, games, and more! 





See your reseller or call today. 1-800-336-6464, ext. 50252 


Canada: 1-800-461-3327 ¢ Internet: http://www.borland.com/ * CompuServe: GO BORLAND 
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